archrip-scan

Files (2)

• SKILL.md
• schema-reference.md

SKILL.md (first lines)

# 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).**

**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) [Inbound (HTTP handlers, CLI), Outbound (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) → Infrastructure(1) [sst.config.ts, CloudFormation] → API Gateway(2) → Lambda Handlers(3) → Services(4) → Domain(5)
- Microservices: External(0) → Infrastructure(1) [Terraform, Pulumi, K8s manifests] → Gateway/BFF(2) → Service Boundaries(3) → Internal Services(4) → Shared Domain(5)

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 entity definitions)
- SQL queries / ORM operations (from repositories, DAOs, or query builders)

**Granularity: one node per real component.** Resist the urge to bundle siblings into umbrella nodes (e.g. a single `domain-shared-models` covering 9 entities, or one `adpt-shared-repos` for every repository implementation). Each Controller, UseCase, abstract Repository, Repository implementation, and Domain Entity is normally its own node. See [schema-reference.md → Node Granularity](schema-reference.md#node-granularity-avoid-over-collapsing) for the exact rule of thumb.

**Repository → Port pattern:** in DDD/Hexagonal projects, every abstract Repository in `domains/` becomes a `port` node (layer = application core), and every concrete implementation in `infrastructures/` becomes an `adapter` node (outer layer). The use case depends on the port; the adapter `implements` the port. See [schema-reference.md → Repository → Port pattern](schema-reference.md#repository--port-pattern-ddd--hexagonal) for the canonical shape.

**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"`
- SQL queries or ORM operations → edge `metadata` with `type: "code"` or `"list"` (see Phase 5)

**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

**Edge type matters.** `dependency` / `implements` / `relation` are not interchangeable. In particular, `implements` edges always flow `adapter → port` — never adapter → entity, adapter → adapter, or adapter → database. If you cannot point an `implements` edge at a `port` node, the abstraction is missing from the diagram and should be added. See [schema-reference.md → Edge type semantics](schema-reference.md#edge-type-semantics).

**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
- Entities → connect to the repository/adapter that references them
- Database nodes → connect to the adapter/repository that queries them
- Infrastructure nodes → connect to the adapter/service they provision

**Edge enrichment — SQL / query details:**
For edges connecting a service/adapter/repository to a database or entity node, include query information:
- `description`: summarize what data operation this edge performs (e.g., "Queries active users by email with JOIN on roles")
- `metadata`: include representative SQL or ORM queries found in the source code

Example:
```json
{
  "source": "adpt-user-repo",
  "target": "db-users",
  "type": "dependency",

From yida29/archrip, MIT.

More from yida29/archrip