Architecture Extractor

Architecture Extractor

Produce a single engineering constitution (docs/engineering_constitution.md) — a handbook that captures a codebase's development philosophy so precisely that a different team (or AI) could build an entirely different product with the same engineering identity.

The output describes HOW the project is built. Never WHAT it does.

---

What this is NOT

Before starting, internalize what to ignore:

• Business logic, domain models, feature implementations
• App-specific entities, endpoint names as literal contracts
• Branding, content, copy, or UI text
• Tutorials, beginner explanations, or setup guides
• Boilerplate without a pattern behind it

Everything you extract must generalize. "The user has a name field" → ignore. "All entities have snake_case columns with created_at/updated_at timestamps" → extract as a rule.

---

Analysis Protocol

Work through these systematically. Don't skip sections because the project seems simple — absence of a pattern is itself a signal worth recording.

Phase 1: Structure Survey

# Run these (adapt paths to the actual project):
find . -type f | grep -v "node_modules\|venv\|__pycache__\|\.git\|dist\|build" | sort
ls -la
cat package.json 2>/dev/null || cat pyproject.toml 2>/dev/null || cat requirements.txt 2>/dev/null

Map:

• Root layout: what lives at the top level and why
• Module/package organization: how code is grouped
• Where boundaries live (feature vs. shared, business vs. infrastructure)
• Config/env file placement
• Test placement relative to source

Phase 2: Entry Points & Lifecycle

Read the main entry point(s). Trace the startup sequence:

• How is the app initialized?
• What happens before requests are served / before the main loop runs?
• How are dependencies wired (DI container, manual, module-level singletons)?
• How does the app shut down?

Phase 3: Layering & Separation of Concerns

Identify the architectural layers. Common patterns: controller/service/repository, router/handler/store, component/hook/service, MVC, hexagonal. Look for:

• Which layer owns validation?
• Which layer owns error formatting?
• Where does business logic live vs. I/O?
• Are layers enforced by folder structure, by import rules, or by convention only?

Phase 4: Naming System

Scan broadly across files. For each category, identify the actual pattern:

• Files: snake_case.py, camelCase.ts, kebab-case.tsx, PascalCase.tsx
• Classes/components: naming suffix patterns (*Service, *Repository, *Controller, *Manager)
• Functions: verb-first vs. noun-first, predicate naming (isActive, hasPermission)
• Database: table names (plural/singular, case), column naming, FK patterns
• Constants: ALL_CAPS, module-namespaced, or typed enums
• Test files: test_*.py, *.test.ts, *.spec.ts — and what they're named after

Phase 5: API & Communication Patterns

If there's an HTTP API:

• URL structure (versioning, resource nesting depth, action verbs vs. nouns)
• Request/response envelope (does every response wrap in { data, error }?)
• Error response shape: what fields, what status codes for what situations
• Auth mechanism: where headers are validated, how identity flows inward
• Pagination, filtering, sorting conventions

If there's async/queue communication:

• Queue naming
• Job/message shape
• Error retry strategy

Phase 6: Validation Philosophy

• Where is validation defined (schema objects, decorator-based, inline)?
• Is it duplicated across layers or owned by one layer?
• Are error messages user-facing or internal?
• How are constraints expressed (lengths, formats, enums)?

Phase 7: Error Handling Strategy

Trace what happens when something goes wrong at each layer:

• How are exceptions caught and converted?
• What reaches the client vs. what's logged internally?
• Is there a global handler? What does it do?
• Are errors typed/classified or are they raw exceptions?

Phase 8: Data Access Patterns

• ORM vs. raw queries vs. query builder
• Connection management (pool, persistent connection, per-request)
• Transaction handling
• Migration strategy (numbered files, auto-migration, manual)

Phase 9: Config & Secrets Management

• How are env vars read (at import time, lazily, via a config class)?
• What's the validation strategy for required config?
• How are defaults handled?
• What's the test override pattern?

Phase 10: Testing Philosophy

• What kind of tests exist (unit, integration, contract, e2e)?
• Where do fixtures/mocks live?
• What's mocked vs. what hits real infrastructure?
• How are test helpers/factories organized?
• What's the naming pattern for test functions?

Phase 11: Async & Concurrency

• Async framework (asyncio, threading, multiprocessing, workers)?
• How is shared state protected?
• Queue/worker topology if present
• Caching layer (what's cached, TTL strategy, cache key naming)

Phase 12: Security Conventions

• Auth/authz separation
• How secrets are compared (timing-safe?)
• Input sanitization philosophy
• What's validated at the boundary vs. trusted internally

Phase 13: Developer Experience

• Linting/formatting tools and configuration
• Pre-commit hooks or CI enforcement
• Environment setup (virtualenv, nvm, docker-compose)
• How local development differs from production

Phase 14: Style, Conventions & Decision Heuristics

• Logging: what is logged, at what level, and what is deliberately NOT logged (secrets, PII, payloads)?
• Function style: typical length, guard-clause usage, nesting depth, explicit vs. inferred types,

early returns, one-object-param vs. long positional lists.

• Shared code: where utilities/helpers/base classes live; how duplication is avoided

(extract-on-second-use? utility vs. service vs. facade?).

• Decision heuristics (infer from repeated choices): when a new service/module/abstraction gets

created, when duplication is tolerated, when NOT to abstract, how external/schema contracts are mirrored.

• Boundary/security posture: what is validated/sanitized at edges vs. trusted internally.

---

Output Format

Generate docs/engineering_constitution.md (create the docs/ directory if needed; fall back to the project root only if there is no clear root). Use exactly this structure. Keep every section — if a section does not apply (e.g., no frontend, no database, no queue), write a one-liner noting its absence rather than deleting the heading. Absence of a pattern is itself a documented decision.

Write it as an official handbook using RFC-2119 keywords (MUST / MUST NOT / SHOULD / SHOULD NOT / MAY). Every section should convey: why the rule exists, when it applies, how to implement it, the anti-pattern it prevents, and a generalized example where useful. Sections 4–8 describe a layered object-oriented server by default — map them to the project's real equivalents (a UI component is a "controller"; an HTTP client + cache + storage is "data access") and mark truly inapplicable ones.

# Engineering Constitution
> Generated from: [project name / path]
> Date: [today]
> Reference stack: [primary language/framework — name it once, then keep every rule generalizable]

## 1. Engineering Philosophy
[3–5 bullets, in priority order, capturing the overall mindset. Infer from what the code prioritizes:
correctness over speed? explicit over magic? consistency over local optimization? DX over raw perf?]

## 2. Project Organization
### Root Layout Rule
### Module / Scope Organization
### Shared vs. Feature Code
### Allowed vs. Forbidden Dependencies
[Include a generalized example tree]

## 3. Architecture Style
### Layer Stack [presentation → application → data → cross-cutting, or the project's equivalent]
### Data Flow & Dependency Direction
### Composition vs. Inheritance
### Lifecycle [bootstrap, initialization, shutdown]

## 4. Controller / Entry-Point Constitution
[The boundary layer that translates outside↔inside: HTTP handlers, UI components, CLI commands,
message consumers — whichever this project has. Cover both server and client entry points if both exist.]
### Responsibilities (and the ONLY things it may do)
### Forbidden Responsibilities
### Input Handling & Delegation
### Response / Return Shape
### MUST / MUST NOT list
[Generalized template]

## 5. Service Constitution
[The layer owning business logic, orchestration, and I/O. Usually the richest section.]
### Responsibilities & Business-Logic Ownership
### Dependencies & Composition [how services call other services / the data layer]
### Method Structure, Length, and How Large Methods Are Split
### Side Effects, Statelessness, Return Values
### Recurring service templates [with generalized pseudo-code]

## 6. Data Access Constitution
### Persistence Abstraction [ORM / repository / query builder / HTTP client / cache / storage]
### Repository Responsibilities & Query Organization
### Transaction Ownership
### Caching Strategy [keys, TTL source, invalidation] — if applicable
### Mapping [raw payload/row → model]

## 7. DTO / Contract Style
### Request / Response Envelopes
### Input Contracts & Defaults
### Immutability & Transformation
### Serialization

## 8. Model / Entity Style
### Construction / Hydration
### Properties & Relations
### Derived Behavior [getters / methods]
### Mutability, Factories, Inheritance
### Timestamp & Soft-Delete Conventions [if persisted]

## 9. Validation Philosophy
### Where Validation Lives [which layer owns what]
### Input vs. Business Validation
### How Constraints Are Expressed & Reused
### Error-Message Ownership

## 10. Error Handling Constitution
### Per-Layer Strategy [what each layer catches vs. propagates]
### Global / Shared Handler Behavior
### What Reaches the User vs. What Is Logged
### Recoverable vs. Unrecoverable Errors

## 11. Logging Philosophy
### When to Log / What to Log / What NOT to Log
### Levels & Correlation
### Sensitive-Data Rules

## 12. Security Standards
### Auth / Authz Architecture
### Secrets Handling [storage, comparison, transport]
### Boundary Validation & Trust Model

## 13. Performance & Scalability Rules
### Caching Philosophy
### Concurrency / Async Model
### Data-Access / Query Optimization Patterns
[If the project has no deliberate performance strategy, say so — absence is a signal.]

## 14. Naming Constitution
[Tabular. State the ACTUAL pattern for each: files, folders, classes, interfaces, functions, variables,
constants, enums, DTOs, models, services, controllers, guards/middleware, private/helper methods,
DB tables/columns, test files, config keys, events/queues, module scopes.]

## 15. Function Writing Style
### Signatures & Return Types
### Guard Clauses & Early Returns
### Nesting Depth & Complexity Limits
### Null / Boolean Handling
### Extraction Philosophy, Formatting & Spacing

## 16. Dependency Rules
### Allowed / Forbidden Direction
### Circular-Dependency Avoidance
### Injection vs. Construction
### Module Boundaries & Path Aliases

## 17. Shared Code Philosophy
### Utilities vs. Services vs. Shared Presentation
### Reuse vs. Intentional Duplication
### Composition, Facades, Base Classes

## 18. Configuration Philosophy
### Config Loading & Typing
### Secrets & Environment Separation
### Constants, Defaults, Feature Flags
### Internationalization / Localization [if applicable]

## 19. Testing Philosophy
### Test Taxonomy & Placement
### Mocking Strategy [mock at the boundary]
### Fixtures / Factories
### Naming & Coverage Priorities
[If the project has NO tests, state that plainly and describe the actual safety net —
types, lint, build, pre-commit gate — as the "test suite of record".]

## 20. Code Consistency Rules
### Language / Framework Baseline [mandatory primitives; forbidden legacy equivalents]
### Enforced Strictness [linter / compiler / formatter rules, verbatim where possible]
### Imports, Ordering, Spacing, Comments
### Magic Numbers / Strings → Named Constants
### Styling System [if applicable]

## 21. Architecture Decision Principles
[Heuristics inferred from repeated choices: when to create a service, when to split a module, when to
introduce an abstraction, when NOT to abstract, when to create a helper, when to duplicate intentionally,
when to generalize toward shared code, how external/schema contracts are mirrored.]

## 22. Reusable Patterns, Anti-Patterns & AI Coding Rules

### Reusable Engineering Patterns
[For each recurring pattern, a generalized pseudo-code template. Examples: CRUD/service pattern,
repository/data-access pattern, worker/job pattern, cache-aside pattern, overlay/notification pattern.]

### Anti-Patterns & Forbidden Practices
[Things the codebase demonstrably avoids — infer from consistent absence. This subsection is NEVER empty.]

### AI Coding Rules
[Convert everything above into explicit, directly-usable agent instructions. This subsection must stand
alone as a coding skill/rulebook.]
#### The AI MUST
- ... [at least 8]
#### The AI MUST NOT
- ...
#### The AI SHOULD
- ...
#### The AI SHOULD NOT
- ...

---

Quality Standards

The output fails if any of these are true:

• It describes business logic (specific entities, endpoints, features) instead of patterns
• Any section is vague ("use good naming") instead of specific ("all service classes are suffixed Service")
• Reusable patterns lack pseudo-structure examples
• The anti-patterns subsection is empty
• The Logging (§11) or Security (§12) section is missing or hand-waved rather than stated as rules
• The AI Coding Rules subsection (§22) has fewer than 8 MUST rules, or is not usable as a standalone skill
• Another AI could not build a different product in this style by following the constitution alone

The output succeeds when:

• Every pattern is inferred from actual code evidence, not assumed
• A principal engineer would recognize their codebase's identity in the document
• The document is specific enough to resolve ambiguous design decisions on a greenfield project
• It is entirely free of app-specific logic

---

Delivery

1. Write docs/engineering_constitution.md (create docs/ if needed).
2. Report a one-paragraph summary of the 3 most distinctive engineering decisions you found —

the choices that most define this codebase's identity vs. the generic default.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 3bsalam-1
• Source: 3bsalam-1/architecture-extractor
• License: MIT

Install and usage instructions live in the source repository linked above.