Architect

Architect (prd-architect) analyzes a JavaScript/TypeScript repository and generates production-quality technical documentation — README, architecture overview, API reference, database schema, environment variables, deployment, and more — from static analysis plus optional AI providers. Every claim in the output is derived from repository evidence; documents without sufficient evidence are omitted and reported, never invented.

Quickstart

npx prd-architect .

This runs generate (the default command) against the current directory and writes a docs/ directory plus docs/architect.context.json. Requires Node.js ≥ 22.

No API key? Use fully local static analysis:

npx prd-architect . --no-ai

Features

• Repository scanning — finds the repo root, respects .gitignore and .architectignore, skips dependencies/build output/binary files, detects the package manager and monorepo layout.
• Deep static analysis — real TypeScript-compiler parsing of .ts/.tsx/.js/.jsx: imports, exports, functions, classes, React components/hooks, and process.env access. Builds a module dependency graph with entry-point and centrality ranking.
• Framework plugins — ten built-in plugins: TypeScript, React, Next.js, NestJS, Express, Fastify, Prisma, Drizzle, Docker, GitHub Actions. They extract routes (App/Pages Router, decorator controllers, app.METHOD, router mounts with prefix composition), database entities and relations, authentication setup, CI workflows, and containers.
• 16 documentation documents — README.md, ARCHITECTURE.md, GETTING_STARTED.md, INSTALLATION.md, FOLDER_STRUCTURE.md, API.md, DATABASE.md, AUTHENTICATION.md, ENVIRONMENT.md, CONFIGURATION.md, DEPLOYMENT.md, FEATURES.md, INTEGRATIONS.md, TESTING.md, SECURITY.md, GLOSSARY.md — each generated only when there is evidence for it, plus a machine-readable architect.context.json (schema version 1).
• Mermaid diagrams — architecture flowchart and ER diagram, syntax-validated before writing.
• AI semantic analysis (optional) — module summaries and an architecture narrative via Anthropic, any OpenAI-compatible endpoint, or local Ollama. Structured outputs are schema-validated with repair retries; three depth levels (quick, standard, deep).
• Graceful degradation — provider failures (auth, network, rate limit) fall back to static-only output, explicitly marked Generated without AI analysis, with a degradation report. No hidden prose.
• Incremental updates — content-hash cache (.architect/) makes update fast; updating an unchanged repository is byte-identical. Marker-based section splicing preserves hand-written content in mixed files.
• Cost control — estimate reports planned requests, tokens, and cost without calling a provider; --budget enforces a hard USD cap (exit code 7) with partial docs preserved.
• Safety by default — secrets are redacted before anything is sent to a provider; env-var values never appear in docs; prompt-injection lines in repository content are filtered; user-owned files are never overwritten without --force.
• Deterministic — stable sorting at every stage; two runs over an unchanged repo produce identical documents.

Commands

| Command | Description | | --- | --- | | generate [path] | Generate documentation from scratch (default command). | | update [path] | Incrementally update previously generated documentation. | | inspect [path] | Show detected technologies and repository stats. No AI, no writes. | | estimate [path] | Report planned AI requests, tokens, and cost. No AI calls, no writes. | | clean [path] | Remove the Architect cache; with --force also Architect-owned files. | | init | Create an annotated architect.config.ts in the current directory. |

Options

| Option | Description | | --- | --- | | --output <path> | Output directory (default: docs). | | --provider <name> | anthropic | openai-compatible | ollama. | | --model <id> | Model ID (defaults: claude-sonnet-4-5, gpt-4o-mini, qwen2.5-coder:32b). | | --base-url <url> | Endpoint for the openai-compatible provider. | | --format <fmt> | markdown | json — primary document format. | | --no-ai | Static-only mode; no provider or API key required. | | --local | Alias for --provider ollama. | | --diagrams / --no-diagrams | Enable/disable Mermaid diagrams (default: on). | | --depth <level> | quick | standard | deep — amount of AI semantic analysis. | | --budget <usd> | Hard AI cost cap in USD; run stops gracefully at the limit (exit 7). | | --estimate | Alias for the estimate command. | | --dry-run | Report planned file writes without writing. | | --diff | Print a unified diff of proposed changes; never writes, never prompts. | | --verbose | Detailed progress and per-stage timing. | | --json | Machine-readable completion summary on stdout. | | --force | Overwrite non-Architect-owned files. | | --no-cache | Ignore existing cache; reprocess everything (cache is still written). | | --include <paths...> | Restrict analysis to these paths (repeatable). | | --exclude <paths...> | Exclude these paths (repeatable). | | --config <path> | Explicit configuration file path. | | --seed <n> | Best-effort determinism seed for providers that support it. |

Configuration

Everything is optional. Priority: CLI flags > ARCHITECT_* environment variables > config file > defaults. Run prd-architect init to generate an annotated config.

// architect.config.ts
import { defineConfig } from "prd-architect";

export default defineConfig({
  output: "./docs",
  provider: "anthropic", // "anthropic" | "openai-compatible" | "ollama"
  // model: "claude-sonnet-4-5",
  // baseUrl: "http://localhost:11434",
  depth: "standard",     // "quick" | "standard" | "deep"
  // budget: 2.0,        // hard USD cap per run (exit code 7 when reached)
  // noAi: false,        // static-only mode
  concurrency: 4,
  include: [],
  exclude: [],
  diagrams: true,
  cache: true,
  agentsMd: false,       // also generate an AGENTS.md for AI coding agents
  documents: {
    readme: true,
    architecture: true,
    api: true,
    database: true,
    authentication: true,
    deployment: true,
  },
});

API keys are read only from the environment — never from the config file: ANTHROPIC_API_KEY, OPENAI_API_KEY, or the generic ARCHITECT_API_KEY.

AI providers

• Anthropic (default) — set ANTHROPIC_API_KEY.
• OpenAI-compatible — --provider openai-compatible --base-url https://…, set OPENAI_API_KEY.
• Ollama (local) — --local (or --provider ollama); runs entirely on your machine against http://localhost:11434 by default.
• None — --no-ai produces the full static document set with zero network calls.

Before any cloud run, the CLI prints exactly what leaves the machine (source excerpts + structured metadata). Configuring a --base-url that does not resolve to a loopback/private address triggers an explicit warning.

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success. | | 1 | General/unexpected error. | | 2 | Invalid configuration or CLI usage (includes a missing API key). | | 3 | Repository not supported (no package.json found). | | 4 | AI provider error (reserved; runs degrade to static-only instead). | | 5 | Parsing error. | | 6 | Output conflict — user-owned files would be overwritten (re-run with --force). | | 7 | AI budget exceeded — partial documentation was written. |

Privacy & security

• Secrets — before any AI request, outgoing content passes a redaction filter for high-entropy strings, known key formats (AWS, Stripe, GitHub, OpenAI, Anthropic, JWT, PEM private keys), and connection strings with embedded credentials. Generated docs document environment variable names only — values never appear in docs, logs, or provider payloads.
• Prompt injection — repository content embedded in prompts is wrapped in explicit untrusted-data delimiters, lines matching injection patterns (ignore all previous instructions, you are now …, system: …) are neutralized with a [FILTERED] marker, and system prompts instruct the model to treat delimited content as data, never instructions.
• Telemetry — none. There is no analytics, tracking, or phone-home of any kind.

Monorepo layout

apps/cli                  # the prd-architect CLI (bin: prd-architect)
packages/
  core                    # pipeline orchestrator (scan → … → render → write)
  scanner                 # repo root detection, file walk, classification
  parser                  # TypeScript-compiler-based source analysis
  graph                   # dependency graph, modules, centrality, Mermaid
  ai                      # provider adapters, redaction, injection guard
  renderer-markdown       # the 16 Markdown documents + markers
  renderer-json           # architect.context.json
  plugin-sdk              # plugin API, config schema, model types, exit codes
  plugin-typescript       # language, testing, library & service detections
  plugin-react            # React / React DOM / React Router
  plugin-nextjs           # App/Pages Router routes, NextAuth, middleware
  plugin-nestjs           # decorator controllers, guards, roles
  plugin-express          # routes, router mounts, JWT/Passport, cors/helmet
  plugin-fastify          # routes, register prefixes, plugins
  plugin-prisma           # schema.prisma entities, relations, datasource
  plugin-drizzle          # pgTable/mysqlTable/sqliteTable entities
  plugin-docker           # Dockerfile / compose / hosting configs
  plugin-github-actions   # CI workflows
  integration-tests       # E2E suite over fixtures/ (private)
fixtures/                 # real fixture repositories (PRD §30.2)

Development

pnpm install
pnpm build      # turbo build across all packages
pnpm test       # turbo test across all packages
pnpm typecheck

Testing

• Unit tests in every package (parser, scanner, graph, plugins, renderers, core stages, CLI).
• Fixture repositories under fixtures/: Next.js SaaS, Express+Drizzle API, Fastify (plain JS), NestJS, React SPA, pnpm monorepo, planted-secrets and prompt-injection repos. Fixture package.json files are props — their dependencies are never installed (fixtures/ is deliberately outside the pnpm workspace).
• End-to-end integration tests (@prd-architect/integration-tests) run the full pipeline programmatically over the fixtures: stack/route/entity detection, document set + determinism (byte-identical re-runs), secret safety (nothing leaks into docs or provider prompts), prompt-injection neutralization, provider-failure degradation, budget enforcement (exit 7), update idempotency, output conflicts (exit 6), and a full snapshot of the generated document set.

Authoring plugins

Plugins implement detect and/or analyze from @prd-architect/plugin-sdk and return typed fragments (TechnologyDetection[], routes, entities, integrations, …) that core merges deterministically. See packages/plugin-sdk/src/plugin.ts for the contract and packages/plugin-express for a complete example (route extraction, auth detection, integrations).

License

MIT