BREVALEN

Products · Open source

Project DNA

The living intelligence layer for software.

Project DNA is a software intelligence engine that understands what a repository is, not just what it contains. It transforms raw source code into structured, queryable, evolving knowledge through deterministic analysis - no AI, no cloud dependencies, fully offline.

View on GitHub →MIT licensed · In active development

Vision

Every repository has a DNA. Today it is invisible.

Every software repository has a unique combination of architecture, complexity, health, risk, business domains, capabilities and evolutionary history. Today that DNA exists only in the heads of senior engineers. Project DNA makes it visible, structured and queryable - producing a comprehensive, versioned, diffable representation of what the software is. Not a summary. Not documentation. Not a diagram. A living model of the software's identity.

What it is not

  • Not an AI coding assistant. It does not write code or suggest completions.
  • Not a documentation generator. It does not produce markdown files or API docs.
  • Not a code search tool. It does not index text or find string matches.
  • Not a static architecture viewer. It does not just draw boxes and arrows.
  • Not a git visualization tool. It does not render commit graphs.
  • Not a repository scanner. Scanning is one small input to a much larger system.

It is a new category: a software intelligence engine that understands the holistic identity of a codebase through deterministic analysis.

Architecture

A layered monorepo with strict dependency inversion.

  1. Layer 1

    Domain models and interfaces (dna-core)

    Defines what exists. Zero logic, zero side effects. Everything depends on it; it depends on nothing.

  2. Layer 2

    Analysis engines

    Scanner, AST parser, dependency resolver, architecture inference, knowledge generator.

  3. Layer 3

    Synthesis engine (dna-engine)

    Fuses raw analysis into a unified identity: DNA objects, DNA graph, repository profile, domains, capabilities.

  4. Layer 4

    Intelligence engine

    Health scoring, complexity profiling, risk assessment, criticality analysis, narrative generation.

  5. Layer 5

    Evolution engine

    Snapshots, diffs, trend analysis, regression detection.

  6. Layer 6

    Storage

    Hybrid persistence: SQLite for structured data, in-memory Graphology for graph operations.

  7. Layer 7

    Presentation

    VS Code extension and webview components consuming the public API.

The pipeline

Ten deterministic stages, from scan to diff.

01

Scan

Repository root in, RepositoryDNA out: languages, frameworks, config files, file manifest.

02

Parse

File contents in, FileDNA out: imports, exports, classes, functions per file.

03

Resolve dependencies

FileDNA in, RepositoryGraph out: the structural dependency graph.

04

Infer architecture

ArchitectureDNA out: detected pattern, layers, confidence, evidence.

05

Generate knowledge

KnowledgeNode and RiskNode collections from structure and conventions.

06

Synthesize DNA

DNA objects, DNA graph, repository profile, business domains, capabilities.

07

Compute intelligence

Health, complexity profile, risk assessment, critical components, repository story.

08

Assemble ProjectDNA

A lightweight aggregate root of summaries and counts; full data loads on demand.

09

Snapshot

A versioned, content-hashed EvolutionSnapshot with extracted metrics.

10

Diff

Two snapshots in, DNADiff out: entity changes, health deltas, risk and topology shifts.

Every stage emits typed events through the EventBus, supports cancellation via AbortSignal, and returns a typed Result for explicit error handling.

Package map

Thirteen packages, one direction of dependency.

PackageLayerResponsibility
@project-dna/sharedInfrastructureResult type, EventBus, DI container, logging, common types
@project-dna/dna-core122 domain models, 9 engine interfaces, pipeline orchestrator
@project-dna/repository-scanner2File system scanning, language and framework detection
@project-dna/ast-engine2TS/JS extraction plus Tree-sitter WASM for Python, Go, Java, Rust, C#
@project-dna/dependency-engine2Dependency graph construction, circular dependency detection
@project-dna/architecture-engine2Heuristic inference: MVC, Clean, Hexagonal, DDD, Layered, Microservice
@project-dna/knowledge-engine2Structured knowledge generation, code smell detection
@project-dna/dna-engine3Entity synthesis, identity inference, domain clustering, semantic graph
@project-dna/software-intelligence-engine4Health, complexity, risk, criticality, narrative
@project-dna/evolution-engine5Snapshot versioning, diffing, trend analysis
@project-dna/storage6Hybrid SQLite and Graphology persistence
@project-dna/ui-components7Webview UI components
vscode-extension7VS Code extension host

Domain model

The vocabulary the engine reasons in.

Core analysis

RepositoryDNA
Raw repository metadata: languages, frameworks, config files
FileDNA
Per-file structure: imports, exports, symbols
ClassDNA
Class metadata: methods, properties, inheritance
FunctionDNA
Function metadata: parameters, return type, complexity
DependencyDNA
Import and export dependency information
ModuleDNA
Logical module groupings
ArchitectureDNA
Detected pattern, layers, confidence scores
KnowledgeNode
Structured knowledge observations
RiskNode
Detected code risks and smells
RepositoryGraph
Sealed structural dependency graph

Synthesis

DNAObject
Enriched entity with purpose, role, criticality, health, relationships
DNAGraph
Semantic graph of domains, capabilities, layers and concepts
RepositoryProfile
Project type, maturity, technology stack, size classification
BusinessDomain
Inferred domain cluster, for example authentication or billing
Capability
Detected functional ability, for example REST API serving

Intelligence

RepositoryHealth
Composite score across five dimensions, 0 to 100
ComplexityProfile
Complexity distribution, coupling metrics, instability indices
RiskAssessment
Aggregated risk with severity distribution and top risks
CriticalComponent
High blast-radius entities via multi-factor scoring
RepositoryStory
Deterministic narrative assembled from structured data

Evolution and root

EvolutionSnapshot
Point-in-time capture with metrics for fast trending
DNADiff
What changed: entities, health, risks, topology
ProjectDNA
The aggregate root and single entry point for querying

Public API

Four focused interfaces. Nothing bypasses them.

IProjectDNAService
  IProjectDNAAnalyzer   analyze(), refresh(), getCurrent(), dispose()
  IProjectDNAQuery      getArchitecture(), getHealth(), getEntities(), getDNAGraph()
  IProjectDNAEvolution  getHistory(), getDiff(), getLatestSnapshot()
  IProjectDNAEvents     onProgress(), onReady()

The public API follows the interface segregation principle. Consumers depend on the narrowest sub-interface they need: commands use the analyzer, UI views use the query interface, progress bars use events. Nothing reaches around it.

Design principles

Deterministic by construction.

Everything works offline

No cloud services, no API keys, no telemetry. The whole system runs locally with zero network dependencies.

AI is never the source of truth

Analysis is deterministic and heuristic. Every fact in ProjectDNA maps to a measurable observation.

Dependency inversion everywhere

The orchestrator depends on interfaces. Engines can be swapped, mocked or upgraded independently.

Result type for fallible work

No thrown exceptions for expected failures - every async operation returns a typed Result.

Technology

Chosen for determinism and portability.

Language
TypeScript 5.7+
Type safety, ecosystem, VS Code integration
Monorepo
Turborepo + PNPM
Fast builds, workspace dependencies, cache
Validation
Zod
Runtime schema validation with type inference
Graph
Graphology
In-memory directed graph with traversal algorithms
Storage
better-sqlite3
Embedded, zero-config, single-file persistence
Testing
Vitest
Fast, TypeScript-native, watch mode
Extension
VS Code Extension API
Target platform for the initial product
Build
TypeScript, esbuild, Vite
Type checking plus extension and webview bundles

Status

What is built, and what comes next.

Implemented

  • 13 packages in a monorepo with a clean dependency graph, all models validated with Zod
  • Repository scanner with recursive traversal, .gitignore support, language and framework detection, limits and cancellation
  • TypeScript, TSX, JavaScript and JSX AST extraction with deterministic hashes and complexity metrics
  • Tree-sitter WASM parsing for Python, Go, Java, Rust and C#
  • Sealed RepositoryGraph with internal, aliased, workspace, dynamic, type-only, re-export and external resolution
  • Linear-time circular dependency detection and module-boundary summaries
  • Architecture inference across six patterns with confidence, evidence and stable IDs
  • Risk detection for complexity, large files, excessive imports, cycles, orphans, unstable modules and oversized barrels
  • Software intelligence engine: health, complexity, risk, criticality and deterministic narrative
  • Evolution engine with snapshot creation, compression and DNA diffing
  • SQLite persistence with workspace restoration and version continuity across restarts
  • VS Code extension with Analyze, Refresh, Generate DNA, Architecture and Knowledge Graph commands
  • Query-backed Architecture, Dependencies, Knowledge Graph, Health, Risks, Critical Components and Evolution views
  • Accessible, keyboard-navigable webview primitives and persisted sidebar navigation
  • Deterministic cross-platform native validation and byte-identical VSIX packaging with a real Extension Host acceptance gate

Next

  • Expand installed-extension integration coverage for actionable intelligence interactions
  • Continue product discovery for the next user-facing intelligence workflow, without changing frozen native and release contracts

Development

pnpm install
Install the workspace (Node 22.23.2, pnpm 9.15.4)
pnpm check:workspace
Validate workspace structure and package scripts
pnpm verify
Full sequential pipeline: validate, format, lint, typecheck, test, build
pnpm test
Run all tests
pnpm typecheck
Type-check all packages
pnpm build
Build packages and the VS Code extension and webview

Open source

Read the source, or talk to us about using it.

View on GitHub →Start a project →