feat: add .architect/ project mapping system with architect-indexer agent and Docker containerization

- Add .architect/ directory structure (10 template files) as project brain for agent orientation - Add architect-indexer agent that scans codebase and generates structured architecture docs - Add Docker containerization: Dockerfile.architect-indexer, docker-compose.architect.yml - Add TypeScript project-mapper module with staleness detection and context injection - Add /index-project command, architect-first-contact rule, project-mapping skill - Integrate orchestrator first-contact check: triggers indexing before any task delegation - Add npm arch:* scripts for Docker-based indexing workflow - Register agent in capability-index.yaml and AGENTS.md
2026-04-22 20:01:38 +01:00
parent 9d85dd9f83
commit 6b71ea2b57
26 changed files with 2160 additions and 3 deletions
--- a/.architect/README.md
+++ b/.architect/README.md
@@ -0,0 +1,93 @@
+# 📐 Project Architecture Index
+
+> **Auto-generated navigation file.** Updated by `architect-indexer` on every pipeline run.
+> **DO NOT edit manually** — changes will be overwritten. Edit source code instead.
+
+## Quick Status
+
+| Metric | Value |
+|--------|-------|
+| Last Indexed | _pending first run_ |
+| Index Version | 1 |
+| Files Tracked | 0 |
+| Modules | 0 |
+| Staleness | _unknown_ |
+
+---
+
+## Navigation
+
+### 🏗 Architecture
+
+| File | Description | When to Read |
+|------|-------------|-------------|
+| [`architecture/overview.md`](architecture/overview.md) | High-level project architecture, layers, boundaries | Before ANY implementation task |
+| [`architecture/dependency-graph.md`](architecture/dependency-graph.md) | Module-to-module dependency graph | Before adding cross-module imports |
+
+### 📦 Entities & Data
+
+| File | Description | When to Read |
+|------|-------------|-------------|
+| [`entities/entities.md`](entities/entities.md) | All domain entities, their fields and relationships | Before creating/editing models or DB tables |
+| [`db-schema/schema.md`](db-schema/schema.md) | Database tables, columns, indexes, foreign keys, migrations | Before touching any migration or DB query |
+
+### 🌐 API Surface
+
+| File | Description | When to Read |
+|------|-------------|-------------|
+| [`api-surface/endpoints.md`](api-surface/endpoints.md) | All API endpoints, methods, auth, request/response types | Before adding/modifying any API endpoint |
+
+### 📏 Conventions
+
+| File | Description | When to Read |
+|------|-------------|-------------|
+| [`conventions/conventions.md`](conventions/conventions.md) | Coding style, naming, patterns, forbidden practices | Before writing ANY code |
+
+### 🔧 Tech Stack
+
+| File | Description | When to Read |
+|------|-------------|-------------|
+| [`tech-stack/stack.md`](tech-stack/stack.md) | Languages, frameworks, libraries, versions | Before adding dependencies or choosing tools |
+
+### 🗺 Machine-Readable Maps
+
+| File | Description | Used By |
+|------|-------------|---------|
+| [`maps/file-graph.json`](maps/file-graph.json) | File → imports/exports graph | `architect-indexer`, `system-analyst`, `lead-developer` |
+| [`maps/module-graph.json`](maps/module-graph.json) | Module → dependencies graph | `system-analyst`, `orchestrator` for routing |
+
+### ⚙️ Machine Config
+
+| File | Description | Used By |
+|------|-------------|---------|
+| [`project.json`](project.json) | Project metadata (name, type, framework, entry points) | `orchestrator` for routing decisions |
+| [`state.json`](state.json) | Index freshness state (hashes, timestamps, version) | `orchestrator` to detect staleness |
+
+---
+
+## How It Works
+
+### For Agents
+
+1. **First contact**: Orchestrator checks `.architect/state.json`
+2. **Stale or missing**: Launch `architect-indexer` to build/update
+3. **Fresh**: Read relevant files from `.architect/` for context
+4. **After changes**: `architect-indexer` incrementally updates affected sections
+
+### For Humans
+
+- Browse any `.md` file for human-readable documentation
+- Check `project.json` for quick project facts
+- See `state.json` for when the index was last updated
+
+### Update Triggers
+
+| Event | Action |
+|-------|--------|
+| New file added/removed | Rebuild `maps/file-graph.json` |
+| New dependency added | Update `tech-stack/stack.md` |
+| Schema migration created | Update `db-schema/schema.md` |
+| New entity/model created | Update `entities/entities.md` |
+| New API endpoint added | Update `api-surface/endpoints.md` |
+| Convention file changed | Update `conventions/conventions.md` |
+| Any structural change | Increment version in `state.json` |
--- a/.architect/api-surface/endpoints.md
+++ b/.architect/api-surface/endpoints.md
@@ -0,0 +1,49 @@
+# API Surface
+
+> Auto-generated by `architect-indexer`. DO NOT edit manually.
+
+## Endpoints
+
+| Method | Path | Auth | Controller | Description |
+|--------|------|------|-----------|-------------|
+| _pending_ | _pending_ | _pending_ | _pending_ | _pending_ |
+
+_This section is populated after the first index run._
+
+## Detailed Endpoint Definitions
+
+### `METHOD /api/path`
+
+**Auth**: Required / None / Optional
+**Rate Limit**: _pending_
+
+**Request**:
+| Field | Type | Required | Validation | Description |
+|-------|------|----------|------------|-------------|
+| _pending_ | _pending_ | _pending_ | _pending_ | _pending_ |
+
+**Response 200**:
+| Field | Type | Description |
+|-------|------|-------------|
+| _pending_ | _pending_ | _pending_ |
+
+**Errors**:
+| Code | Condition | Message |
+|------|-----------|---------|
+| 400 | Validation failed | _pending_ |
+| 401 | Unauthorized | _pending_ |
+| 404 | Not found | _pending_ |
+
+---
+
+## API Versioning
+
+| Version | Base Path | Status | Notes |
+|---------|-----------|--------|-------|
+| _pending_ | _pending_ | current | _pending_ |
+
+## Authentication
+
+| Method | Header / Param | Scope |
+|--------|---------------|-------|
+| Bearer JWT | `Authorization: Bearer <token>` | _pending_ |
--- a/.architect/architecture/dependency-graph.md
+++ b/.architect/architecture/dependency-graph.md
@@ -0,0 +1,35 @@
+# Dependency Graph
+
+> Auto-generated by `architect-indexer`. DO NOT edit manually.
+
+## Module Dependencies
+
+```
+Module A ──→ Module B ──→ Module C
+   │              │
+   └──→ Module D ─┘
+```
+
+_This section is populated after the first index run._
+
+## Import Graph
+
+| Module | Imports From | Imported By |
+|--------|-------------|-------------|
+| _pending_ | _pending_ | _pending_ |
+
+## Circular Dependencies
+
+_None detected_ (or listed with paths)
+
+## External Dependencies
+
+| Package | Version | Used By | Purpose |
+|---------|---------|---------|---------|
+| _pending_ | _pending_ | _pending_ | _pending_ |
+
+## Dependency Rules
+
+1. **No cross-layer imports upward** — Infrastructure cannot import Application
+2. **No circular dependencies** — A → B → A is forbidden
+3. **Shared kernel only** — Cross-module communication via events/interfaces
--- a/.architect/architecture/overview.md
+++ b/.architect/architecture/overview.md
@@ -0,0 +1,53 @@
+# Architecture Overview
+
+> Auto-generated by `architect-indexer`. DO NOT edit manually.
+
+## Project Type
+
+_This section is populated after the first index run._
+
+## Architecture Pattern
+
+_Example: Layered, Clean Architecture, MVC, MVVM, Microservices, Monolith, etc._
+
+## Layers
+
+| Layer | Directory | Responsibility |
+|-------|-----------|---------------|
+| _pending_ | _pending_ | _pending_ |
+
+## Module Boundaries
+
+| Module | Directory | Exports | Dependencies |
+|--------|-----------|---------|-------------|
+| _pending_ | _pending_ | _pending_ | _pending_ |
+
+## External Services
+
+| Service | Purpose | Integration Point |
+|---------|---------|-------------------|
+| _pending_ | _pending_ | _pending_ |
+
+## Key Decisions
+
+| Decision | Rationale | Date |
+|----------|-----------|------|
+| _pending_ | _pending_ | _pending_ |
+
+## Diagram
+
+```
+┌──────────────────────────────────┐
+│         Presentation             │
+│  (Controllers, Views, Routes)   │
+├──────────────────────────────────┤
+│         Application              │
+│     (Services, Use Cases)        │
+├──────────────────────────────────┤
+│          Domain                  │
+│  (Entities, Value Objects)       │
+├──────────────────────────────────┤
+│        Infrastructure            │
+│  (Repositories, External APIs)   │
+└──────────────────────────────────┘
+```
--- a/.architect/conventions/conventions.md
+++ b/.architect/conventions/conventions.md
@@ -0,0 +1,68 @@
+# Project Conventions
+
+> Auto-generated by `architect-indexer`. DO NOT edit manually.
+
+## Naming Conventions
+
+| Element | Pattern | Example |
+|---------|---------|---------|
+| Files | _pending_ | _pending_ |
+| Variables | _pending_ | _pending_ |
+| Classes | _pending_ | _pending_ |
+| Functions | _pending_ | _pending_ |
+| Constants | _pending_ | _pending_ |
+| Database tables | _pending_ | _pending_ |
+| API endpoints | _pending_ | _pending_ |
+
+_This section is populated after the first index run._
+
+## Code Patterns
+
+| Pattern | When to Use | Example File |
+|---------|------------|-------------|
+| Repository | Data access | _pending_ |
+| Service | Business logic | _pending_ |
+| Controller | HTTP handling (thin) | _pending_ |
+| Event | Cross-module communication | _pending_ |
+| Value Object | Immutable type | _pending_ |
+
+## Architectural Patterns
+
+1. **Service Layer** — Business logic in services, not controllers
+2. **Repository Pattern** — Data access abstracted behind interfaces
+3. **Thin Controllers** — Controllers delegate to services, max 10 lines per method
+4. **Event-Driven** — Cross-module via events, never direct model imports
+
+## Maximum Sizes
+
+| Element | Max | Enforcement |
+|---------|-----|-------------|
+| File | 100 lines | Architect check |
+| Function | 30 lines | Lint rule |
+| Class methods | 5 public | Code review |
+| Controller method | 10 lines | Code review |
+
+## Forbidden Practices
+
+1. ❌ Direct model imports from other modules
+2. ❌ Business logic in controllers
+3. ❌ Raw SQL queries outside repositories
+4. ❌ Hardcoded secrets or credentials
+5. ❌ Mutable global state
+6. ❌ Catching exceptions silently
+
+## Testing Conventions
+
+| Type | Location | Naming |
+|------|----------|--------|
+| Unit | _pending_ | `{name}.test.{ext}` |
+| Integration | _pending_ | `{name}.integration.test.{ext}` |
+| E2E | _pending_ | `{name}.e2e.test.{ext}` |
+
+## Git Conventions
+
+| Convention | Pattern |
+|-----------|---------|
+| Branch naming | `feature/{issue}-{slug}` |
+| Commit prefix | `feat:`, `fix:`, `refactor:`, `test:`, `docs:` |
+| PR naming | `#{issue}: brief description` |
--- a/.architect/db-schema/schema.md
+++ b/.architect/db-schema/schema.md
@@ -0,0 +1,45 @@
+# Database Schema
+
+> Auto-generated by `architect-indexer`. DO NOT edit manually.
+
+## Tables
+
+| Table | Engine | Rows (est.) | Description |
+|-------|--------|-------------|-------------|
+| _pending_ | _pending_ | _pending_ | _pending_ |
+
+_This section is populated after the first index run._
+
+## Table Definitions
+
+### `_table_name`
+
+| Column | Type | Nullable | Default | Index | Foreign Key |
+|--------|------|----------|---------|-------|-------------|
+| id | _pending_ | NO | auto | PK | — |
+
+**Indexes:**
+| Name | Columns | Type | Purpose |
+|------|---------|------|---------|
+| _pending_ | _pending_ | _pending_ | _pending_ |
+
+---
+
+## Foreign Key Graph
+
+```
+TableA.id ←── TableB.table_a_id
+TableB.id ←── TableC.table_b_id
+```
+
+## Migration History
+
+| Migration | Date | Tables Affected | Reversible |
+|----------|------|-----------------|-----------|
+| _pending_ | _pending_ | _pending_ | _pending_ |
+
+## Seeded Data
+
+| Table | Records | Purpose |
+|-------|---------|---------|
+| _pending_ | _pending_ | _pending_ |
--- a/.architect/entities/entities.md
+++ b/.architect/entities/entities.md
@@ -0,0 +1,47 @@
+# Domain Entities
+
+> Auto-generated by `architect-indexer`. DO NOT edit manually.
+
+## Entity List
+
+| Entity | Module | Primary Key | Description |
+|--------|--------|-------------|-------------|
+| _pending_ | _pending_ | _pending_ | _pending_ |
+
+## Entity Relationships
+
+```
+EntityA ──1:N──→ EntityB
+   │                  │
+   └──N:M──→ EntityC ─┘
+```
+
+_This section is populated after the first index run._
+
+## Detailed Entity Definitions
+
+### _EntityName_
+
+| Field | Type | Nullable | Default | Description |
+|-------|------|----------|---------|-------------|
+| id | _pending_ | No | auto | _pending_ |
+
+**Relations:**
+- _pending_
+
+**Business Rules:**
+- _pending_
+
+---
+
+## Value Objects
+
+| Value Object | Type | Used By | Validation |
+|-------------|------|---------|------------|
+| _pending_ | _pending_ | _pending_ | _pending_ |
+
+## Enums
+
+| Enum | Values | Used By |
+|------|--------|---------|
+| _pending_ | _pending_ | _pending_ |
--- a/.architect/project.json
+++ b/.architect/project.json
@@ -0,0 +1,42 @@
+{
+  "version": 1,
+  "indexed_at": "",
+  "project": {
+    "name": "",
+    "type": "",
+    "framework": "",
+    "language": "",
+    "description": "",
+    "repository": "",
+    "entry_points": [],
+    "rootDir": ""
+  },
+  "structure": {
+    "directories": {},
+    "key_files": {}
+  },
+  "tech_stack": {
+    "languages": [],
+    "frameworks": [],
+    "databases": [],
+    "runtimes": [],
+    "package_managers": [],
+    "testing_frameworks": [],
+    "ci_cd": []
+  },
+  "modules": [],
+  "conventions": {
+    "naming": {
+      "files": "",
+      "variables": "",
+      "classes": "",
+      "functions": "",
+      "constants": ""
+    },
+    "patterns": [],
+    "forbidden": []
+  },
+  "entities": [],
+  "api_endpoints": [],
+  "db_tables": []
+}
--- a/.architect/state.json
+++ b/.architect/state.json
@@ -0,0 +1,71 @@
+{
+  "version": 1,
+  "status": "not_indexed",
+  "last_full_index": null,
+  "last_incremental_update": null,
+  "last_file_count": 0,
+  "file_hashes": {},
+  "directory_hashes": {},
+  "dependency_hashes": {
+    "package_json": null,
+    "composer_json": null,
+    "go_mod": null,
+    "pubspec_yaml": null,
+    "cargo_toml": null,
+    "requirements_txt": null
+  },
+  "sections": {
+    "architecture_overview": {
+      "last_updated": null,
+      "file_hash": null,
+      "status": "stale"
+    },
+    "dependency_graph": {
+      "last_updated": null,
+      "file_hash": null,
+      "status": "stale"
+    },
+    "entities": {
+      "last_updated": null,
+      "file_hash": null,
+      "status": "stale"
+    },
+    "db_schema": {
+      "last_updated": null,
+      "file_hash": null,
+      "status": "stale"
+    },
+    "api_surface": {
+      "last_updated": null,
+      "file_hash": null,
+      "status": "stale"
+    },
+    "conventions": {
+      "last_updated": null,
+      "file_hash": null,
+      "status": "stale"
+    },
+    "tech_stack": {
+      "last_updated": null,
+      "file_hash": null,
+      "status": "stale"
+    },
+    "file_graph": {
+      "last_updated": null,
+      "file_hash": null,
+      "status": "stale"
+    },
+    "module_graph": {
+      "last_updated": null,
+      "file_hash": null,
+      "status": "stale"
+    }
+  },
+  "staleness_threshold_hours": 24,
+  "indexing_agent": "architect-indexer",
+  "pipeline_integration": {
+    "check_on_first_contact": true,
+    "incremental_on_file_change": true,
+    "full_reindex_on_dependency_change": true
+  }
+}
--- a/.architect/tech-stack/stack.md
+++ b/.architect/tech-stack/stack.md
@@ -0,0 +1,57 @@
+# Tech Stack
+
+> Auto-generated by `architect-indexer`. DO NOT edit manually.
+
+## Runtime & Platform
+
+| Component | Version | Purpose |
+|-----------|---------|---------|
+| Language | _pending_ | _pending_ |
+| Runtime | _pending_ | _pending_ |
+| Package Manager | _pending_ | _pending_ |
+
+_This section is populated after the first index run._
+
+## Framework
+
+| Framework | Version | Purpose |
+|-----------|---------|---------|
+| _pending_ | _pending_ | _pending_ |
+
+## Database
+
+| Engine | Version | Purpose | Connection |
+|--------|---------|---------|------------|
+| _pending_ | _pending_ | _pending_ | _pending_ |
+
+## Key Dependencies
+
+| Package | Version | Purpose | Critical |
+|---------|---------|---------|----------|
+| _pending_ | _pending_ | _pending_ | _pending_ |
+
+## Development Tools
+
+| Tool | Version | Purpose |
+|------|---------|---------|
+| Linter | _pending_ | _pending_ |
+| Formatter | _pending_ | _pending_ |
+| Test Runner | _pending_ | _pending_ |
+| Type Checker | _pending_ | _pending_ |
+
+## Infrastructure
+
+| Component | Technology | Purpose |
+|-----------|-----------|---------|
+| Web Server | _pending_ | _pending_ |
+| Cache | _pending_ | _pending_ |
+| Queue | _pending_ | _pending_ |
+| Storage | _pending_ | _pending_ |
+| CI/CD | _pending_ | _pending_ |
+
+## Environment Variables
+
+| Variable | Required | Default | Purpose |
+|----------|----------|---------|---------|
+| NODE_ENV | No | development | Environment |
+| _pending_ | _pending_ | _pending_ | _pending_ |