# Architecture Extractor > > - **Type:** Skill - **Install:** `agentstack add skill-3bsalam-1-architecture-extractor-architecture-extractor` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [3bsalam-1](https://agentstack.voostack.com/s/3bsalam-1) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [3bsalam-1](https://github.com/3bsalam-1) - **Source:** https://github.com/3bsalam-1/architecture-extractor ## Install ```sh agentstack add skill-3bsalam-1-architecture-extractor-architecture-extractor ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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. ```markdown # 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](https://github.com/3bsalam-1) - **Source:** [3bsalam-1/architecture-extractor](https://github.com/3bsalam-1/architecture-extractor) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-3bsalam-1-architecture-extractor-architecture-extractor - Seller: https://agentstack.voostack.com/s/3bsalam-1 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.