Open Source · TypeScript · Zero Runtime Deps

Full-Stack Visual
Lineage Compiler

TraceGrid bridges your database schema, API routes, and frontend components into a single architecture.md source-of-truth — then serves it as an interactive JSON graph for your visual canvas.

Get started View on GitHub

Database ERD

User

id · email · passwordHash

Post

id · title · authorId FK

Comment

id · text · postId FK

User → Post (writes)

Post → Comment (has)

→

API Request Flow

GET /api/posts

POST /api/posts

GET /api/posts/:id

POST /api/users

DEL /api/posts/:id

PATCH /api/users/:id

→

Frontend Directory

PostList.tsx

fetch('/api/posts')

PostDetail.tsx

fetch('/api/posts/:id')

UserProfile.tsx

axios.get('/api/users/me')

RegisterForm.tsx

fetch('/api/users')

How it works

Two modes. One source of truth.

TraceGrid operates bi-directionally. Start from an idea or scan what already exists — either way, you end up with a structured, machine-readable architecture.md.

🌱

Greenfield Mode

Give TraceGrid an idea string or a PRD document. The tracegrid-architect AI mode designs the normalized DB schema, API route inventory, directory structure, and request flows — then writes architecture.md before a single line of code is written.

tracegrid init

🔍

Brownfield Mode

Point TraceGrid at an existing codebase. The scanner inspects Prisma schemas, SQL DDL, TypeORM entities, Express/Next.js/FastAPI routes, and React fetch hooks — then compiles everything into architecture.md.

tracegrid scan

📡

Graph Serve Mode

architecture.md already exists? TraceGrid parses it directly into a { nodes, edges } JSON graph and serves it via HTTP — hot-reload safe, ready to feed any visual canvas or analysis tool.

tracegrid serve

CLI Reference

Four commands. Full coverage.

All commands compile to a single Node.js executable in packages/cli/dist/index.js.

init

scan

serve

validate

Greenfield mode — generates a starter architecture.md from an idea string or PRD file.

# From a free-text idea
node packages/cli/dist/index.js init "A SaaS invoicing app with team workspaces"

# From an existing PRD file
node packages/cli/dist/index.js init ./docs/prd.md --out architecture.md

# With scaffold notice
node packages/cli/dist/index.js init "Task management platform" --scaffold

Brownfield mode — scan a directory and compile architecture.md.

# Scan current directory
node packages/cli/dist/index.js scan .

# Scan a specific backend service
node packages/cli/dist/index.js scan ./apps/api --out api-arch.md

# Output:
#  🔍 Scanning: /your/project
#     Found: 12 DB tables, 34 API routes, 18 frontend components
#  ✅ Written to: architecture.md

Serve the graph JSON API — reads architecture.md on every request.

node packages/cli/dist/index.js serve --port 4000

# 🟢 TraceGrid server running on http://localhost:4000

# Available endpoints:
curl http://localhost:4000/graph          # { nodes, edges }
curl http://localhost:4000/graph/nodes    # { nodes }
curl http://localhost:4000/graph/edges    # { edges }
curl http://localhost:4000/health         # { status: "ok" }

Validate architecture.md against the canonical schema and report graph statistics.

node packages/cli/dist/index.js validate
# ✅ architecture.md is valid
#    DB tables:        3
#    Relationships:    3
#    API routes:       6
#    Request flows:    4
#    Graph nodes:      13
#    Graph edges:      13

node packages/cli/dist/index.js validate --json  # machine-readable

Scanner

Detects what you already have.

The scanner reads file contents only — no subprocess execution, no dynamic imports. Each sub-scanner is a pure function: (content, filePath) => ScanResult.

Database Layer

Prisma .prisma

SQL DDL .sql

TypeORM @Entity

Sequelize define()

API Layer

Express router.get/post

Next.js App Router

Next.js Pages API

FastAPI @router.get

Frontend Layer

fetch()

axios.get/post/put

useSWR()

useQuery()

architecture.md Schema

Four sections. Always required.

The canonical schema is enforced by a deterministic parser. A missing or malformed section throws a ParseError — never silent partial results.

§ Database Schema — Mermaid erDiagram block

## Database Schema

```mermaid
erDiagram
  User {
    int    id    PK
    string email
    string passwordHash
  }
  Post {
    int    id       PK
    string title
    int    authorId FK
  }
  User ||--o{ Post : "writes"
```

§ API Routes — Markdown table

## API Routes

| Method | Path           | Handler                | Description     |
|--------|----------------|------------------------|-----------------|
| GET    | /api/posts     | postController.list    | List all posts  |
| POST   | /api/posts     | postController.create  | Create a post   |
| GET    | /api/posts/:id | postController.get     | Get single post |

§ Directory Structure — Fenced tree

## Directory Structure

```
myapp/
├── src/
│   ├── controllers/
│   │   └── postController.ts
│   └── models/
│       └── Post.ts
└── package.json
```

§ Request Flows — Markdown table

## Request Flows

| Feature    | Frontend Component | Endpoint            | DB Tables   |
|------------|--------------------|---------------------|-------------|
| List Posts | PostList           | GET /api/posts      | Post, User  |
| Create Post| PostForm           | POST /api/posts     | Post        |
| View Post  | PostDetail         | GET /api/posts/:id  | Post, Comment |

Core API

TypeScript-first. Zero dependencies.

Import from @tracegrid/core in any TypeScript or Node.js project. All public functions have explicit return types. No any.

TraceNode

A single entity in the graph — DB table, API endpoint, or frontend component.

id: string
label: string
tier: "database" | "api" | "frontend"
kind: "table" | "endpoint" | "component"
meta: Record<string, unknown>

TraceEdge

A directed relationship between two nodes with a semantic type.

ArchitectureSpec

Full in-memory representation of architecture.md.

database: DatabaseSchema
routes: APIRoute[]
directoryTree: string
requestFlows: RequestFlow[]

TraceGraph

The structured graph format consumed by the visual canvas.

nodes: TraceNode[]
edges: TraceEdge[]

parseToGraph()

Convenience: parse architecture.md string → TraceGraph in one call.

param source: string
returns TraceGraph

scanDirectory()

Scan a project directory. Returns raw DB, API, and frontend lineage data.

param  dir: string
returns ScanResult
  db: DBScanResult
  api: APIScanResult
  frontend: FrontendScanResult

Design Principles

Opinionated by design.

Every architectural decision in TraceGrid follows these five constraints.

Schema-first

architecture.md is committed before any code. No DB migration without a schema entry. No API endpoint without a route table row.

Deterministic parsing

Identical input always produces identical { nodes, edges } output. No heuristics, no probabilistic guessing in the parser layer.

Pure scanner functions

Every sub-scanner is (content, filePath) => ScanResult. No subprocess execution, no dynamic imports, no side effects.

Zero core dependencies

@tracegrid/core has no runtime npm dependencies. Only the Node.js standard library. CLI adds only express and commander.

Strict TypeScript

noUncheckedIndexedAccess, strict: true, explicit return types on all public functions. No any in core types or parser.

Round-trip safety

The generator must produce output that the parser can parse without loss. Same structure in, same structure out — always.

Full-Stack VisualLineage Compiler