archrip 0.2.10 → 0.2.12

package/dist/viewer-template/src/index.css

@@ -48,12 +48,15 @@
   --cat-adapter-bg: #ffedd5;
   --cat-adapter-border: #f97316;
   --cat-adapter-text: #9a3412;
-  --cat-model-bg: #fee2e2;
-  --cat-model-border: #ef4444;
-  --cat-model-text: #991b1b;
+  --cat-entity-bg: #fee2e2;
+  --cat-entity-border: #ef4444;
+  --cat-entity-text: #991b1b;
   --cat-database-bg: #fef3c7;
   --cat-database-border: #d97706;
   --cat-database-text: #92400e;
+  --cat-infrastructure-bg: #e0e7ff;
+  --cat-infrastructure-border: #6366f1;
+  --cat-infrastructure-text: #3730a3;
   --cat-external-bg: #f3f4f6;
   --cat-external-border: #6b7280;
   --cat-external-text: #374151;
@@ -107,12 +110,15 @@
   --cat-adapter-bg: #2b1a0a;
   --cat-adapter-border: #fb923c;
   --cat-adapter-text: #fdba74;
-  --cat-model-bg: #2b1111;
-  --cat-model-border: #f87171;
-  --cat-model-text: #fca5a5;
+  --cat-entity-bg: #2b1111;
+  --cat-entity-border: #f87171;
+  --cat-entity-text: #fca5a5;
   --cat-database-bg: #2b1f06;
   --cat-database-border: #fbbf24;
   --cat-database-text: #fde68a;
+  --cat-infrastructure-bg: #1e1b4b;
+  --cat-infrastructure-border: #818cf8;
+  --cat-infrastructure-text: #a5b4fc;
   --cat-external-bg: #1e2330;
   --cat-external-border: #9ca3af;
   --cat-external-text: #d1d5db;

package/dist/viewer-template/src/types.ts

@@ -1,47 +1,3 @@
-// ─── Depth system ───
-
-export type DepthLevel = 0 | 1 | 2;
-
-export function computeDepths(nodes: { layer: number }[]): Map<number, DepthLevel> {
-  if (nodes.length === 0) return new Map();
-  const layers = [...new Set(nodes.map(n => n.layer))].sort((a, b) => a - b);
-
-  const map = new Map<number, DepthLevel>();
-
-  // Flat / workflow: filtering not useful — always show all
-  if (layers.length <= 2) {
-    for (const l of layers) map.set(l, 0);
-    return map;
-  }
-
-  // Exactly 3 layers: 1:1:1 mapping
-  if (layers.length === 3) {
-    map.set(layers[0], 0);
-    map.set(layers[1], 1);
-    map.set(layers[2], 2);
-    return map;
-  }
-
-  // 4+ layers: equal thirds
-  const min = layers[0];
-  const max = layers[layers.length - 1];
-  const range = max - min;
-  const t1 = min + range / 3;
-  const t2 = min + (2 * range) / 3;
-  for (const l of layers) {
-    if (l <= t1) map.set(l, 0);
-    else if (l <= t2) map.set(l, 1);
-    else map.set(l, 2);
-  }
-  return map;
-}
-
-export const DEPTH_LEVELS = [
-  { level: 0 as const, label: 'Overview' },
-  { level: 1 as const, label: 'Structure' },
-  { level: 2 as const, label: 'Detail' },
-] as const;
-
 // ─── Category system ───
 // Standard 8 categories. Custom categories are allowed — they get a fallback color.
 
@@ -62,9 +18,10 @@ const CATEGORY_META = {
   service:    { label: 'Service',    icon: '\u{2699}\u{FE0F}', color: { bg: '#dcfce7', border: '#22c55e', text: '#166534' } },
   port:       { label: 'Port',       icon: '\u{1F50C}', color: { bg: '#ede9fe', border: '#8b5cf6', text: '#5b21b6' } },
   adapter:    { label: 'Adapter',    icon: '\u{1F527}', color: { bg: '#ffedd5', border: '#f97316', text: '#9a3412' } },
-  model:      { label: 'Entity',     icon: '\u{1F4BE}', color: { bg: '#fee2e2', border: '#ef4444', text: '#991b1b' } },
-  database:   { label: 'DB / Infra', icon: '\u{1F5C4}\u{FE0F}', color: { bg: '#fef3c7', border: '#d97706', text: '#92400e' } },
-  external:   { label: 'External',   icon: '\u{2601}\u{FE0F}', color: { bg: '#f3f4f6', border: '#6b7280', text: '#374151' } },
+  entity:     { label: 'Entity',     icon: '\u{1F4BE}', color: { bg: '#fee2e2', border: '#ef4444', text: '#991b1b' } },
+  database:       { label: 'Database',       icon: '\u{1F5C4}\u{FE0F}', color: { bg: '#fef3c7', border: '#d97706', text: '#92400e' } },
+  infrastructure: { label: 'Infrastructure', icon: '\u{1F3D7}\u{FE0F}', color: { bg: '#e0e7ff', border: '#6366f1', text: '#3730a3' } },
+  external:       { label: 'External',       icon: '\u{2601}\u{FE0F}', color: { bg: '#f3f4f6', border: '#6b7280', text: '#374151' } },
   job:        { label: 'Job',        icon: '\u{23F0}', color: { bg: '#fef9c3', border: '#eab308', text: '#854d0e' } },
   dto:        { label: 'DTO',        icon: '\u{1F4E6}', color: { bg: '#cffafe', border: '#06b6d4', text: '#155e75' } },
 } as const satisfies Record<string, CategoryMeta>;
@@ -77,7 +34,7 @@ function getMeta(category: string): CategoryMeta {
   return CATEGORY_META[category as StandardCategory] ?? FALLBACK_META;
 }
 
-const STANDARD_CATEGORIES = ['controller', 'service', 'port', 'adapter', 'model', 'database', 'external', 'job', 'dto'] as const;
+const STANDARD_CATEGORIES = ['controller', 'service', 'port', 'adapter', 'entity', 'database', 'infrastructure', 'external', 'job', 'dto'] as const;
 
 export function getCategoryColors(category: string): CategoryStyle {
   const key = (STANDARD_CATEGORIES as readonly string[]).includes(category) ? category : 'fallback';
@@ -127,19 +84,10 @@ export interface MetadataEntry {
   type?: 'text' | 'code' | 'link' | 'list';
 }
 
-export interface MemberNodeSummary {
-  id: string;
-  label: string;
-  description: string;
-  filePath: string;
-  sourceUrl: string;
-}
-
 export interface ArchNodeData {
   [key: string]: unknown;
   label: string;
   category: string;
-  depth: DepthLevel;
   description: string;
   filePath: string;
   sourceUrl: string;
@@ -152,13 +100,6 @@ export interface ArchNodeData {
   implements?: string;
   externalService?: string;
   metadata?: MetadataEntry[];
-  isGroup?: boolean;
-  memberCount?: number;
-  memberNodes?: MemberNodeSummary[];
-}
-
-export function isGroupNode(data: ArchNodeData): boolean {
-  return data.isGroup === true;
 }
 
 export interface UseCase {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archrip",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Generate interactive architecture diagrams from your codebase using AI agents",
   "type": "module",
   "bin": {

package/dist/templates/slash-commands/codex/archrip-scan.md

@@ -1,222 +0,0 @@
----
-description: Scan codebase and generate architecture diagram data
----
-
-# archrip scan — Analyze codebase architecture
-
-Analyze the current codebase and generate `.archrip/architecture.json`.
-
-**Language rule:** Respond in the same language as the user's message or `$ARGUMENTS`. If no user text is available, detect the project's primary language from README/docs and match it. The `architecture.json` fields (labels, descriptions) should also use that language.
-
-## Phase 1: Project Discovery
-1. Read top-level files (package.json, composer.json, go.mod, Cargo.toml, pom.xml, pyproject.toml, etc.)
-2. Identify language, framework, source root
-3. List directory structure (2 levels deep)
-4. Auto-detect `sourceUrl`: Run `git remote get-url origin` and convert to browse URL:
-   - `git@github.com:org/repo.git` → `https://github.com/org/repo/blob/main/{filePath}`
-   - `https://github.com/org/repo.git` → `https://github.com/org/repo/blob/main/{filePath}`
-   - `git@gitlab.com:org/repo.git` → `https://gitlab.com/org/repo/-/blob/main/{filePath}`
-   - If no git remote, leave empty (ask in Phase 7)
-
-## Phase 2: Documentation Discovery
-Read existing documentation to understand architecture context:
-1. Check for: README.md, CLAUDE.md, docs/, doc/, wiki/, ARCHITECTURE.md, CONTRIBUTING.md, ADR/
-2. For each document, extract and take notes on:
-   - **Business context**: What problem does this system solve? Who are the users?
-   - **Component responsibilities**: What each module/service does and why it exists
-   - **Design decisions & constraints**: Why certain patterns/libraries were chosen, known limitations
-   - **Data flow**: How data moves through the system (request lifecycle, event flow, etc.)
-   - **External integrations**: What external services are used, why, and how
-   - **Non-functional requirements**: SLAs, performance targets, security policies
-   - **Deployment & infrastructure**: Hosting, CI/CD, environment details
-3. Keep these notes — you will use them in Phase 4 to write rich node/edge descriptions and metadata
-
-## Phase 3: Layer Identification
-Assign each component a `layer` integer. The rule: **higher layer = closer to domain core (more stable, fewer external dependencies). Lower layer = closer to external world (more volatile, I/O-bound).**
-
-Both layouts use this value — dagre places higher layers lower on screen, concentric places them at the center.
-
-**Reference mappings** (layer numbers in parentheses — adapt to actual project structure):
-
-MVC / Layered:
-- Laravel: External(0) → Controllers(1) → Services(2) → Domain(3)
-- Rails: External(0) → Controllers(1) → Services(2) → Domain(3)
-- Django: External(0) → Views(1) → Serializers(2) → Services(3) → Domain(4)
-- Spring Boot: External(0) → Controllers(1) → Services(2) → Repositories(3) → Domain(4)
-- NestJS: External(0) → Controllers(1) → Services(2) → Repositories(3) → Domain(4)
-- Next.js App Router: External(0) → Route Handlers/Pages(1) → Components(2) → Hooks/Services(3) → Data Access(4)
-- FastAPI: External(0) → Routers(1) → Services(2) → Repositories(3) → Domain(4)
-
-DDD / Clean Architecture / Hexagonal (use `"layout": "concentric"`):
-- Generic: External(0) → Adapters(1) [Controllers, DB impl, API clients] → Application Core(2) [Use Cases / Application Services, Ports] → Domain(3)
-- Go (Hex): External(0) → Adapters(1) [Handlers, Repositories] → Application Core(2) [Use Cases, Ports] → Domain(3)
-- Flutter (Clean): External(0) → Data Sources(1) → Repositories(2) → Use Cases(3) → Domain(4)
-- Note: Ports are interfaces owned by the **application core** (use cases / application services; sometimes placed in domain, but not required). Adapters implement outbound Ports and call inbound Ports. For layering, Ports should be at the same layer as the application core (or 1 step closer to Domain), never at the adapter layer.
-
-CQRS / Event-Driven:
-- CQRS: External(0) → Command Handlers / Query Handlers(1) → Application Services(2) → Domain(3). Command and Query sides share the same layer structure but separate models
-- Event Sourcing: External(0) → Command Handlers(1) → Event Store(2) → Projections(3) → Read Models(4)
-- Event-Driven (Motia, Temporal, etc.): External(0) → API Steps(1) → Event Steps(2) → Services(3) → Domain(4)
-
-Serverless / Microservices:
-- SST/Lambda: External(0) → API Gateway(1) → Lambda Handlers(2) → Services(3) → Domain(4)
-- Microservices: External(0) → Gateway/BFF(1) → Service Boundaries(2) → Internal Services(3) → Shared Domain(4)
-
-Modular Monolith:
-- Generic: External(0) → Module APIs(1) [public interfaces] → Module Internal Services(2) → Shared Kernel / Domain(3)
-
-For unlisted frameworks: group by directory responsibility and apply the abstract rule above.
-
-## Phase 4: Read Key Files
-For each layer, read representative files to extract:
-- Component names and purposes
-- Dependencies (imports, injections)
-- Public methods/routes
-- Database schemas (from migrations or model definitions)
-
-**Enrich descriptions from documentation:** Cross-reference code with your Phase 2 notes.
-For each component, compose a `description` (1-3 sentences) that covers:
-- **What**: Its responsibility (from code analysis)
-- **Why**: Business context or design rationale (from docs)
-- **How**: Key implementation details, constraints, or patterns worth noting
-
-A good description tells the reader something they cannot see from the label alone.
-- BAD: "User service" (just echoes the label)
-- GOOD: "Handles user registration, login, and profile management. Uses JWT for session tokens with 24h expiry. Password hashing via bcrypt (cost=12)."
-
-Also identify metadata candidates:
-- SLA/performance notes → `metadata` with `type: "list"`
-- Related doc links → `metadata` with `type: "link"`
-- Infrastructure details (Lambda ARN, DB engine, etc.) → `metadata` with `type: "code"` or `"text"`
-
-**Do NOT read every file.** Focus on entry points, core logic, interfaces, and data models.
-
-## Phase 5: Map Relationships
-For each component, identify:
-- What it depends on (imports, constructor injection)
-- What depends on it
-- External service connections
-
-**Connectivity check:** After mapping, verify every node has at least one edge. If a node is orphaned:
-- DTOs/entities → connect to the service or adapter that references them
-- External services → connect to the adapter/controller that integrates with them
-- Models → connect to the adapter/repository that queries them
-
-## Phase 6: Identify Use Cases
-Group related components into user-facing features.
-
-## Phase 7: Draft Review — STOP and ask the developer
-
-**IMPORTANT: Do NOT proceed to Phase 8 until the developer responds. You MUST stop here and wait for input.**
-
-Present a summary of what you found:
-- **Documents read**: List all docs you read in Phase 2 (e.g., README.md, CLAUDE.md, docs/architecture.md)
-- List of discovered nodes (grouped by layer/category)
-- List of discovered use cases
-- External services found
-
-Then ask:
-- Are there other documents you should read? (e.g., docs/, wiki/, design docs)
-- Are there missing components, external services, or use cases?
-- Should anything be excluded?
-- `sourceUrl` auto-detected as: `<detected-url>` — correct? (If not detected, ask for the `sourceUrl` template, e.g., `https://github.com/org/repo/blob/main/{filePath}`)
-
-End your message with: **"Please review and reply with corrections, or type 'go' to generate."**
-
-**Do NOT write architecture.json yet. Wait for the developer to respond.**
-
-If the developer replies with corrections, apply them and present the updated summary. Repeat until they say "go" / "ok" / "skip".
-
-## Phase 8: Generate architecture.json
-Only run this phase AFTER the developer has approved the draft in Phase 7.
-
-Create `.archrip/` directory if it doesn't exist, then write the complete `.archrip/architecture.json` following the schema, incorporating developer feedback.
-
-After writing the file:
-1. Run `npx archrip serve` in the terminal — it auto-builds and opens the browser. **Do NOT run `npx archrip build` separately or open the browser manually** (serve handles everything).
-2. Tell the developer: Run `/archrip-update` to make further adjustments (add/remove nodes, fix relationships, etc.)
-
-### Required structure (use EXACTLY these field names)
-
-```json
-{
-  "version": "1.0",
-  "project": { "name": "...", "sourceUrl": "https://github.com/org/repo/blob/main/{filePath}" },
-  "nodes": [
-    { "id": "ctrl-users", "category": "controller", "label": "UsersController", "layer": 1, "filePath": "src/controllers/users.ts", "useCases": ["uc-user-mgmt"] }
-  ],
-  "edges": [
-    { "source": "ctrl-users", "target": "svc-users", "type": "dependency" }
-  ],
-  "useCases": [
-    { "id": "uc-user-mgmt", "name": "User Management", "nodeIds": ["ctrl-users", "svc-users"] }
-  ]
-}
-```
-
-**Critical field names — do NOT use alternatives:**
-- Node: `id`, `category`, `label` (NOT name), `layer` — all required
-- Edge: `source`, `target` (NOT from/to) — all required
-- UseCase: `id`, `name`, `nodeIds` — all required
-
-### Node Rules
-- `id`: kebab-case, prefixed by category abbreviation (ctrl-, svc-, port-, adpt-, model-, db-, ext-, job-, dto-)
-- `layer`: non-negative integer. **Higher = closer to domain core / more stable. Lower = closer to external world / more volatile.** Dagre (TB) places higher layers lower on screen; concentric places them at center. Use as many layers as the architecture requires (typically 3-6). Example for DDD/Hex: 0=external, 1=adapters (controllers + infra), 2=application core (use cases/app services + ports), 3=domain. Example for MVC: 0=external, 1=controllers, 2=services, 3=domain.
-- `category`: one of controller, service, port, adapter, model, database, external, job, dto (or custom). Use `model` for domain entities/value objects (core business logic). Use `database` for DB tables, migrations, ORMs, and infrastructure persistence.
-- `label`: display name for the node
-- `description`: 1-3 sentences explaining responsibility + business context. Do NOT just echo the label. Cross-reference documentation for richer context (see Description Guidelines below)
-- `filePath`: relative from project root
-- `depth` (optional): 0=overview, 1=structure, 2=detail. Auto-inferred from `layer` if omitted: with 3+ unique layers, lowest → 0, middle → 1, highest → 2. With 1-2 layers, all nodes get depth 0 (always visible).
-- `useCases`: array of use case IDs this node participates in
-- `metadata` (optional): array of `{ label, value, type? }` entries for supplementary info (AWS ARNs, doc links, SLA notes, etc.). `type` is `text` (default), `code`, `link`, or `list`. `value` is a string, or `string[]` when `type` is `list`. Example:
-  ```json
-  "metadata": [
-    { "label": "Lambda ARN", "value": "arn:aws:lambda:ap-northeast-1:123:function:auth", "type": "code" },
-    { "label": "API Docs", "value": "https://docs.example.com/auth", "type": "link" },
-    { "label": "SLA", "value": ["99.9% uptime", "p95 < 200ms"], "type": "list" }
-  ]
-  ```
-
-### Edge Rules
-- `source`: source node id
-- `target`: target node id
-- `type`: dependency | implements | relation
-- `description` (optional): human-readable description of the edge's purpose
-- `metadata` (optional): same format as node metadata — array of `{ label, value, type? }` entries
-- Only include significant architectural dependencies (not utility imports)
-- **Every node MUST have at least one edge.** If a node has no obvious dependency, connect it with a `relation` edge to the component that uses or contains it.
-
-### Layout Selection
-- DDD / Clean Architecture / Hexagonal / Onion Architecture → add `"layout": "concentric"` to `project`
-- MVC / standard layered → `"layout": "dagre"` (default, can be omitted)
-
-### Description Guidelines
-
-#### Node `description`
-Write 1-3 sentences that explain responsibility AND business context.
-Cross-reference project documentation (README, CLAUDE.md, docs/) for richer context.
-- BAD: "User service" (just echoes the label)
-- BAD: "Handles users" (too vague)
-- GOOD: "Handles user registration, authentication, and profile management. Uses JWT for session tokens; password hashing via bcrypt. Rate-limited to 10 req/s per IP."
-
-#### Edge `description`
-Explain WHY the dependency exists, not just THAT it exists.
-- BAD: "calls" / "depends on"
-- GOOD: "Delegates payment processing via Stripe SDK; retries on timeout (3x with exponential backoff)"
-
-#### `metadata` for supplementary details
-Use `metadata` to capture information from docs that doesn't fit in `description`:
-```json
-"metadata": [
-  { "label": "SLA", "value": ["99.9% uptime", "p95 < 200ms"], "type": "list" },
-  { "label": "Design Doc", "value": "https://...", "type": "link" },
-  { "label": "Infrastructure", "value": "Lambda + DynamoDB (on-demand)", "type": "text" },
-  { "label": "Rate Limit", "value": "10 req/s per IP", "type": "text" }
-]
-```
-
-### Schema Rules
-- Include table schema only when migration files or model annotations are available
-- Reference from node data using schema key name
-
-$ARGUMENTS

package/dist/templates/slash-commands/codex/archrip-update.md

@@ -1,39 +0,0 @@
----
-description: Update or refine the architecture diagram
----
-
-# archrip update — Update architecture diagram
-
-Read `.archrip/architecture.json` and update it.
-
-## Mode 1: Auto-detect from git diff (no arguments)
-
-If `$ARGUMENTS` is empty:
-
-1. Run `git diff --name-only HEAD~10` to find changed files
-2. Read the current `.archrip/architecture.json`
-3. For each changed file:
-   - New component? → Add node + edges
-   - Removed component? → Remove node + edges + use case references
-   - Changed dependencies? → Update edges
-4. Preserve existing node IDs for unchanged components
-5. Write updated `.archrip/architecture.json`
-
-## Mode 2: Apply requested changes (with arguments)
-
-If `$ARGUMENTS` is provided, apply the user's requested changes:
-- Add/remove/modify nodes
-- Fix relationships
-- Add/modify use cases
-- Adjust layer assignments
-- Add database schemas
-- Add/modify metadata entries
-- Improve descriptions
-
-Write the updated `.archrip/architecture.json`.
-
-## After Update
-
-After writing the file, run `npx archrip serve` in the terminal to rebuild and preview the updated diagram.
-
-$ARGUMENTS

package/dist/templates/slash-commands/gemini/archrip-scan.md

@@ -1,222 +0,0 @@
----
-description: Scan codebase and generate architecture diagram data
----
-
-# archrip scan — Analyze codebase architecture
-
-Analyze the current codebase and generate `.archrip/architecture.json`.
-
-**Language rule:** Respond in the same language as the user's message or `$ARGUMENTS`. If no user text is available, detect the project's primary language from README/docs and match it. The `architecture.json` fields (labels, descriptions) should also use that language.
-
-## Phase 1: Project Discovery
-1. Read top-level files (package.json, composer.json, go.mod, Cargo.toml, pom.xml, pyproject.toml, etc.)
-2. Identify language, framework, source root
-3. List directory structure (2 levels deep)
-4. Auto-detect `sourceUrl`: Run `git remote get-url origin` and convert to browse URL:
-   - `git@github.com:org/repo.git` → `https://github.com/org/repo/blob/main/{filePath}`
-   - `https://github.com/org/repo.git` → `https://github.com/org/repo/blob/main/{filePath}`
-   - `git@gitlab.com:org/repo.git` → `https://gitlab.com/org/repo/-/blob/main/{filePath}`
-   - If no git remote, leave empty (ask in Phase 7)
-
-## Phase 2: Documentation Discovery
-Read existing documentation to understand architecture context:
-1. Check for: README.md, CLAUDE.md, docs/, doc/, wiki/, ARCHITECTURE.md, CONTRIBUTING.md, ADR/
-2. For each document, extract and take notes on:
-   - **Business context**: What problem does this system solve? Who are the users?
-   - **Component responsibilities**: What each module/service does and why it exists
-   - **Design decisions & constraints**: Why certain patterns/libraries were chosen, known limitations
-   - **Data flow**: How data moves through the system (request lifecycle, event flow, etc.)
-   - **External integrations**: What external services are used, why, and how
-   - **Non-functional requirements**: SLAs, performance targets, security policies
-   - **Deployment & infrastructure**: Hosting, CI/CD, environment details
-3. Keep these notes — you will use them in Phase 4 to write rich node/edge descriptions and metadata
-
-## Phase 3: Layer Identification
-Assign each component a `layer` integer. The rule: **higher layer = closer to domain core (more stable, fewer external dependencies). Lower layer = closer to external world (more volatile, I/O-bound).**
-
-Both layouts use this value — dagre places higher layers lower on screen, concentric places them at the center.
-
-**Reference mappings** (layer numbers in parentheses — adapt to actual project structure):
-
-MVC / Layered:
-- Laravel: External(0) → Controllers(1) → Services(2) → Domain(3)
-- Rails: External(0) → Controllers(1) → Services(2) → Domain(3)
-- Django: External(0) → Views(1) → Serializers(2) → Services(3) → Domain(4)
-- Spring Boot: External(0) → Controllers(1) → Services(2) → Repositories(3) → Domain(4)
-- NestJS: External(0) → Controllers(1) → Services(2) → Repositories(3) → Domain(4)
-- Next.js App Router: External(0) → Route Handlers/Pages(1) → Components(2) → Hooks/Services(3) → Data Access(4)
-- FastAPI: External(0) → Routers(1) → Services(2) → Repositories(3) → Domain(4)
-
-DDD / Clean Architecture / Hexagonal (use `"layout": "concentric"`):
-- Generic: External(0) → Adapters(1) [Controllers, DB impl, API clients] → Application Core(2) [Use Cases / Application Services, Ports] → Domain(3)
-- Go (Hex): External(0) → Adapters(1) [Handlers, Repositories] → Application Core(2) [Use Cases, Ports] → Domain(3)
-- Flutter (Clean): External(0) → Data Sources(1) → Repositories(2) → Use Cases(3) → Domain(4)
-- Note: Ports are interfaces owned by the **application core** (use cases / application services; sometimes placed in domain, but not required). Adapters implement outbound Ports and call inbound Ports. For layering, Ports should be at the same layer as the application core (or 1 step closer to Domain), never at the adapter layer.
-
-CQRS / Event-Driven:
-- CQRS: External(0) → Command Handlers / Query Handlers(1) → Application Services(2) → Domain(3). Command and Query sides share the same layer structure but separate models
-- Event Sourcing: External(0) → Command Handlers(1) → Event Store(2) → Projections(3) → Read Models(4)
-- Event-Driven (Motia, Temporal, etc.): External(0) → API Steps(1) → Event Steps(2) → Services(3) → Domain(4)
-
-Serverless / Microservices:
-- SST/Lambda: External(0) → API Gateway(1) → Lambda Handlers(2) → Services(3) → Domain(4)
-- Microservices: External(0) → Gateway/BFF(1) → Service Boundaries(2) → Internal Services(3) → Shared Domain(4)
-
-Modular Monolith:
-- Generic: External(0) → Module APIs(1) [public interfaces] → Module Internal Services(2) → Shared Kernel / Domain(3)
-
-For unlisted frameworks: group by directory responsibility and apply the abstract rule above.
-
-## Phase 4: Read Key Files
-For each layer, read representative files to extract:
-- Component names and purposes
-- Dependencies (imports, injections)
-- Public methods/routes
-- Database schemas (from migrations or model definitions)
-
-**Enrich descriptions from documentation:** Cross-reference code with your Phase 2 notes.
-For each component, compose a `description` (1-3 sentences) that covers:
-- **What**: Its responsibility (from code analysis)
-- **Why**: Business context or design rationale (from docs)
-- **How**: Key implementation details, constraints, or patterns worth noting
-
-A good description tells the reader something they cannot see from the label alone.
-- BAD: "User service" (just echoes the label)
-- GOOD: "Handles user registration, login, and profile management. Uses JWT for session tokens with 24h expiry. Password hashing via bcrypt (cost=12)."
-
-Also identify metadata candidates:
-- SLA/performance notes → `metadata` with `type: "list"`
-- Related doc links → `metadata` with `type: "link"`
-- Infrastructure details (Lambda ARN, DB engine, etc.) → `metadata` with `type: "code"` or `"text"`
-
-**Do NOT read every file.** Focus on entry points, core logic, interfaces, and data models.
-
-## Phase 5: Map Relationships
-For each component, identify:
-- What it depends on (imports, constructor injection)
-- What depends on it
-- External service connections
-
-**Connectivity check:** After mapping, verify every node has at least one edge. If a node is orphaned:
-- DTOs/entities → connect to the service or adapter that references them
-- External services → connect to the adapter/controller that integrates with them
-- Models → connect to the adapter/repository that queries them
-
-## Phase 6: Identify Use Cases
-Group related components into user-facing features.
-
-## Phase 7: Draft Review — STOP and ask the developer
-
-**IMPORTANT: Do NOT proceed to Phase 8 until the developer responds. You MUST stop here and wait for input.**
-
-Present a summary of what you found:
-- **Documents read**: List all docs you read in Phase 2 (e.g., README.md, CLAUDE.md, docs/architecture.md)
-- List of discovered nodes (grouped by layer/category)
-- List of discovered use cases
-- External services found
-
-Then ask:
-- Are there other documents you should read? (e.g., docs/, wiki/, design docs)
-- Are there missing components, external services, or use cases?
-- Should anything be excluded?
-- `sourceUrl` auto-detected as: `<detected-url>` — correct? (If not detected, ask for the `sourceUrl` template, e.g., `https://github.com/org/repo/blob/main/{filePath}`)
-
-End your message with: **"Please review and reply with corrections, or type 'go' to generate."**
-
-**Do NOT write architecture.json yet. Wait for the developer to respond.**
-
-If the developer replies with corrections, apply them and present the updated summary. Repeat until they say "go" / "ok" / "skip".
-
-## Phase 8: Generate architecture.json
-Only run this phase AFTER the developer has approved the draft in Phase 7.
-
-Create `.archrip/` directory if it doesn't exist, then write the complete `.archrip/architecture.json` following the schema, incorporating developer feedback.
-
-After writing the file:
-1. Run `npx archrip serve` in the terminal — it auto-builds and opens the browser. **Do NOT run `npx archrip build` separately or open the browser manually** (serve handles everything).
-2. Tell the developer: Run `/archrip-update` to make further adjustments (add/remove nodes, fix relationships, etc.)
-
-### Required structure (use EXACTLY these field names)
-
-```json
-{
-  "version": "1.0",
-  "project": { "name": "...", "sourceUrl": "https://github.com/org/repo/blob/main/{filePath}" },
-  "nodes": [
-    { "id": "ctrl-users", "category": "controller", "label": "UsersController", "layer": 1, "filePath": "src/controllers/users.ts", "useCases": ["uc-user-mgmt"] }
-  ],
-  "edges": [
-    { "source": "ctrl-users", "target": "svc-users", "type": "dependency" }
-  ],
-  "useCases": [
-    { "id": "uc-user-mgmt", "name": "User Management", "nodeIds": ["ctrl-users", "svc-users"] }
-  ]
-}
-```
-
-**Critical field names — do NOT use alternatives:**
-- Node: `id`, `category`, `label` (NOT name), `layer` — all required
-- Edge: `source`, `target` (NOT from/to) — all required
-- UseCase: `id`, `name`, `nodeIds` — all required
-
-### Node Rules
-- `id`: kebab-case, prefixed by category abbreviation (ctrl-, svc-, port-, adpt-, model-, db-, ext-, job-, dto-)
-- `layer`: non-negative integer. **Higher = closer to domain core / more stable. Lower = closer to external world / more volatile.** Dagre (TB) places higher layers lower on screen; concentric places them at center. Use as many layers as the architecture requires (typically 3-6). Example for DDD/Hex: 0=external, 1=adapters (controllers + infra), 2=application core (use cases/app services + ports), 3=domain. Example for MVC: 0=external, 1=controllers, 2=services, 3=domain.
-- `category`: one of controller, service, port, adapter, model, database, external, job, dto (or custom). Use `model` for domain entities/value objects (core business logic). Use `database` for DB tables, migrations, ORMs, and infrastructure persistence.
-- `label`: display name for the node
-- `description`: 1-3 sentences explaining responsibility + business context. Do NOT just echo the label. Cross-reference documentation for richer context (see Description Guidelines below)
-- `filePath`: relative from project root
-- `depth` (optional): 0=overview, 1=structure, 2=detail. Auto-inferred from `layer` if omitted: with 3+ unique layers, lowest → 0, middle → 1, highest → 2. With 1-2 layers, all nodes get depth 0 (always visible).
-- `useCases`: array of use case IDs this node participates in
-- `metadata` (optional): array of `{ label, value, type? }` entries for supplementary info (AWS ARNs, doc links, SLA notes, etc.). `type` is `text` (default), `code`, `link`, or `list`. `value` is a string, or `string[]` when `type` is `list`. Example:
-  ```json
-  "metadata": [
-    { "label": "Lambda ARN", "value": "arn:aws:lambda:ap-northeast-1:123:function:auth", "type": "code" },
-    { "label": "API Docs", "value": "https://docs.example.com/auth", "type": "link" },
-    { "label": "SLA", "value": ["99.9% uptime", "p95 < 200ms"], "type": "list" }
-  ]
-  ```
-
-### Edge Rules
-- `source`: source node id
-- `target`: target node id
-- `type`: dependency | implements | relation
-- `description` (optional): human-readable description of the edge's purpose
-- `metadata` (optional): same format as node metadata — array of `{ label, value, type? }` entries
-- Only include significant architectural dependencies (not utility imports)
-- **Every node MUST have at least one edge.** If a node has no obvious dependency, connect it with a `relation` edge to the component that uses or contains it.
-
-### Layout Selection
-- DDD / Clean Architecture / Hexagonal / Onion Architecture → add `"layout": "concentric"` to `project`
-- MVC / standard layered → `"layout": "dagre"` (default, can be omitted)
-
-### Description Guidelines
-
-#### Node `description`
-Write 1-3 sentences that explain responsibility AND business context.
-Cross-reference project documentation (README, CLAUDE.md, docs/) for richer context.
-- BAD: "User service" (just echoes the label)
-- BAD: "Handles users" (too vague)
-- GOOD: "Handles user registration, authentication, and profile management. Uses JWT for session tokens; password hashing via bcrypt. Rate-limited to 10 req/s per IP."
-
-#### Edge `description`
-Explain WHY the dependency exists, not just THAT it exists.
-- BAD: "calls" / "depends on"
-- GOOD: "Delegates payment processing via Stripe SDK; retries on timeout (3x with exponential backoff)"
-
-#### `metadata` for supplementary details
-Use `metadata` to capture information from docs that doesn't fit in `description`:
-```json
-"metadata": [
-  { "label": "SLA", "value": ["99.9% uptime", "p95 < 200ms"], "type": "list" },
-  { "label": "Design Doc", "value": "https://...", "type": "link" },
-  { "label": "Infrastructure", "value": "Lambda + DynamoDB (on-demand)", "type": "text" },
-  { "label": "Rate Limit", "value": "10 req/s per IP", "type": "text" }
-]
-```
-
-### Schema Rules
-- Include table schema only when migration files or model annotations are available
-- Reference from node data using schema key name
-
-$ARGUMENTS