archrip 0.2.3 → 0.2.5

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

@@ -20,9 +20,16 @@ Analyze the current codebase and generate `.archrip/architecture.json`.
 
 ## 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
-2. Extract: system overview, component descriptions, external service integrations, design decisions
-3. Use this knowledge to inform the analysis — documentation often reveals architectural intent that code alone does not show (use cases, business context, external dependencies)
+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).**
@@ -41,9 +48,10 @@ MVC / Layered:
 - FastAPI: External(0) → Routers(1) → Services(2) → Repositories(3) → Models(4)
 
 DDD / Clean Architecture / Hexagonal (use `"layout": "concentric"`):
-- Generic: External(0) → Adapters(1) → Controllers(2) → Application Services(3) → Ports(4) → Domain Entities(5)
-- Go (Hex): External(0) → Handlers(1) → Adapters(2) → Use Cases(3) → Ports(4) → Domain(5)
+- Generic: External(0) → Adapters(1) [Controllers, DB impl, API clients] → Application Services(2) → Ports(3) [domain-defined interfaces] → Domain Entities(4)
+- Go (Hex): External(0) → Adapters(1) [Handlers, Repositories] → Use Cases(2) → Ports(3) → Domain(4)
 - Flutter (Clean): External(0) → Data Sources(1) → Repositories(2) → Use Cases(3) → Entities(4)
+- Note: Ports are interfaces **defined by the domain** — they belong near domain core, not at the adapter layer. Adapters implement/use Ports from the outside.
 
 Serverless / Microservices:
 - SST/Lambda: External(0) → API Gateway(1) → Lambda Handlers(2) → Services(3) → Domain(4)
@@ -58,6 +66,21 @@ For each layer, read representative files to extract:
 - 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
@@ -130,9 +153,10 @@ After writing the file:
 
 ### 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: 0=external, 1=adapters, 2=controllers, 3=app services, 4=ports, 5=domain entities. Example for MVC: 0=external, 1=controllers, 2=services, 3=models.
+- `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: 0=external, 1=adapters (controllers + infra), 2=app services, 3=ports, 4=domain entities. Example for MVC: 0=external, 1=controllers, 2=services, 3=models.
 - `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
@@ -158,6 +182,31 @@ After writing the file:
 - 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

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

@@ -20,9 +20,16 @@ Analyze the current codebase and generate `.archrip/architecture.json`.
 
 ## 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
-2. Extract: system overview, component descriptions, external service integrations, design decisions
-3. Use this knowledge to inform the analysis — documentation often reveals architectural intent that code alone does not show (use cases, business context, external dependencies)
+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).**
@@ -41,9 +48,10 @@ MVC / Layered:
 - FastAPI: External(0) → Routers(1) → Services(2) → Repositories(3) → Models(4)
 
 DDD / Clean Architecture / Hexagonal (use `"layout": "concentric"`):
-- Generic: External(0) → Adapters(1) → Controllers(2) → Application Services(3) → Ports(4) → Domain Entities(5)
-- Go (Hex): External(0) → Handlers(1) → Adapters(2) → Use Cases(3) → Ports(4) → Domain(5)
+- Generic: External(0) → Adapters(1) [Controllers, DB impl, API clients] → Application Services(2) → Ports(3) [domain-defined interfaces] → Domain Entities(4)
+- Go (Hex): External(0) → Adapters(1) [Handlers, Repositories] → Use Cases(2) → Ports(3) → Domain(4)
 - Flutter (Clean): External(0) → Data Sources(1) → Repositories(2) → Use Cases(3) → Entities(4)
+- Note: Ports are interfaces **defined by the domain** — they belong near domain core, not at the adapter layer. Adapters implement/use Ports from the outside.
 
 Serverless / Microservices:
 - SST/Lambda: External(0) → API Gateway(1) → Lambda Handlers(2) → Services(3) → Domain(4)
@@ -58,6 +66,21 @@ For each layer, read representative files to extract:
 - 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
@@ -130,9 +153,10 @@ After writing the file:
 
 ### 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: 0=external, 1=adapters, 2=controllers, 3=app services, 4=ports, 5=domain entities. Example for MVC: 0=external, 1=controllers, 2=services, 3=models.
+- `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: 0=external, 1=adapters (controllers + infra), 2=app services, 3=ports, 4=domain entities. Example for MVC: 0=external, 1=controllers, 2=services, 3=models.
 - `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
@@ -158,6 +182,31 @@ After writing the file:
 - 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

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

@@ -20,9 +20,16 @@ Analyze the current codebase and generate `.archrip/architecture.json`.
 
 ## 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
-2. Extract: system overview, component descriptions, external service integrations, design decisions
-3. Use this knowledge to inform the analysis — documentation often reveals architectural intent that code alone does not show (use cases, business context, external dependencies)
+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).**
@@ -41,9 +48,10 @@ MVC / Layered:
 - FastAPI: External(0) → Routers(1) → Services(2) → Repositories(3) → Models(4)
 
 DDD / Clean Architecture / Hexagonal (use `"layout": "concentric"`):
-- Generic: External(0) → Adapters(1) → Controllers(2) → Application Services(3) → Ports(4) → Domain Entities(5)
-- Go (Hex): External(0) → Handlers(1) → Adapters(2) → Use Cases(3) → Ports(4) → Domain(5)
+- Generic: External(0) → Adapters(1) [Controllers, DB impl, API clients] → Application Services(2) → Ports(3) [domain-defined interfaces] → Domain Entities(4)
+- Go (Hex): External(0) → Adapters(1) [Handlers, Repositories] → Use Cases(2) → Ports(3) → Domain(4)
 - Flutter (Clean): External(0) → Data Sources(1) → Repositories(2) → Use Cases(3) → Entities(4)
+- Note: Ports are interfaces **defined by the domain** — they belong near domain core, not at the adapter layer. Adapters implement/use Ports from the outside.
 
 Serverless / Microservices:
 - SST/Lambda: External(0) → API Gateway(1) → Lambda Handlers(2) → Services(3) → Domain(4)
@@ -58,6 +66,21 @@ For each layer, read representative files to extract:
 - 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
@@ -130,9 +153,10 @@ After writing the file:
 
 ### 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: 0=external, 1=adapters, 2=controllers, 3=app services, 4=ports, 5=domain entities. Example for MVC: 0=external, 1=controllers, 2=services, 3=models.
+- `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: 0=external, 1=adapters (controllers + infra), 2=app services, 3=ports, 4=domain entities. Example for MVC: 0=external, 1=controllers, 2=services, 3=models.
 - `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
@@ -158,6 +182,31 @@ After writing the file:
 - 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

package/package.json

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