aif-architecture

# Architecture - Generate Architecture Guidelines Generate `.ai-factory/ARCHITECTURE.md` with architecture decisions tailored to the project. ## Workflow ### Step 0: Load Config & Project Context **FIRST:** Read `.ai-factory/config.yaml` if it exists to resolve: - **Paths:** `paths.description` and `paths.architecture` - **Language:** `language.ui` for prompts and `language.artifacts` for generated architecture content When invoked by `/aif`, assume `.ai-factory/config.yaml` has already been written for the current setup run and already contains the resolved `language.ui` / `language.artifacts` values. If config.yaml doesn't exist, use defaults: - DESCRIPTION.md: `.ai-factory/DESCRIPTION.md` - ARCHITECTURE.md: `.ai-factory/ARCHITECTURE.md` - Language: `en` (English) **THEN:** Read `.ai-factory/DESCRIPTION.md` (use path from config) if it exists to understand: - Tech stack (language, framework, database, ORM) - Project size and complexity - Core features and requirements - Non-functional requirements **If `.ai-factory/DESCRIPTION.md` does not exist:** ``` ⚠️ No project description found. Run /aif first to set up project context, or describe your project manually: - What are you building? - Tech stack (language, framework, database)? - Team size? - Expected scale? ``` Allow standalone usage — if user provides manual input, use that instead. **Read `.ai-factory/skill-context/aif-architecture/SKILL.md`** — MANDATORY if the file exists. This file contains project-specific rules accumulated by `/aif-evolve` from patches, codebase conventions, and tech-stack analysis. These rules are tailored to the current project. **How to apply skill-context rules:** - Treat them as **project-level overrides** for this skill's general instructions - When a skill-context rule conflicts with a general rule written in this SKILL.md, **the skill-context rule wins** (more specific context takes priority — same principle as nested CLAUDE.md files) - When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context - Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults — they exist because the project's experience proved the default insufficient - **CRITICAL:** skill-context rules apply to ALL outputs of this skill — including the ARCHITECTURE.md template. The template in this SKILL.md is a **base structure**. If a skill-context rule says "architecture doc MUST include X" or "MUST cover section Y" — you MUST augment the template accordingly. Generating ARCHITECTURE.md that violates skill-context rules is a bug. **Enforcement:** After generating any output artifact, verify it against all skill-context rules. If any rule is violated — fix the output before presenting it to the user. ### Step 1: Analyze & Recommend Based on project context, evaluate against the decision matrix and recommend an architecture: **If `$ARGUMENTS` specifies an architecture** (e.g., `/aif-architecture clean`): - Use that architecture directly, skip to Step 2 **If no specific architecture requested:** - Evaluate the project against the decision matrix (see Knowledge Base below) - Consider: team size, domain complexity, scale requirements, tech stack - Present recommendation via `AskUserQuestion`: ``` Based on your project context: - [reason 1 from project analysis] - [reason 2 from project analysis] Which architecture pattern should we use? 1. [Recommended pattern] (Recommended) — [why it fits] 2. [Alternative 1] — [brief reason] 3. [Alternative 2] — [brief reason] 4. [Alternative 3] — [brief reason] ``` Architecture options: - **Clean Architecture** — strict dependency inversion, good for complex business logic - **Domain-Driven Design (DDD)** — bounded contexts, good for complex domains with multiple subdomains - **Microservices** — independent deployment, good for large teams with clear domain boundaries - **Modular Monolith** — single deployment with strong module boundaries, good default for most projects - **Layered Architecture** — simple layers (presentation → business → data), good for smaller projects ### Step 2: Generate the Architecture Artifact Create the parent directory for the resolved architecture path if needed. Generate the resolved architecture artifact (default: `.ai-factory/ARCHITECTURE.md`) with the following structure, **adapted to the project's tech stack and language**: ```markdown # Architecture: [Pattern Name] ## Overview [1-2 paragraphs: what this architecture is and why it was chosen for THIS project] ## Decision Rationale - **Project type:** [from DESCRIPTION.md] - **Tech stack:** [language, framework] - **Key factor:** [primary reason for this choice] ## Folder Structure \`\`\` [folder structure adapted to the project's tech stack] [use actual framework conventions — e.g., Next.js app/ dir, Laravel app/ dir, Go cmd/ dir] \`\`\` ## Dependency Rules [What depends on what. Inner vs outer layers. Module boundaries.] - ✅ [allowed dependency direction] - ❌ [forbidden dependency direction] ## Layer/Module Communication [How layers or modules communicate with each other] - [pattern 1] - [pattern 2] ## Key Principles 1. [Principle 1 — adapted to this project] 2. [Principle 2] 3. [Principle 3] ## Code Examples ### [Example 1 title] \`\`\`[language] [code example in the project's language/framework] \`\`\` ### [Example 2 title] \`\`\`[language] [code example showing dependency rule] \`\`\` ## Anti-Patterns - ❌ [What NOT to do in this architecture] - ❌ [Common mistake to avoid] ``` **Rules for generation:** - Adapt ALL examples to the project's language and framework (don't use TypeScript examples for a Go project) - Use the project's actual conventions (import paths, naming, etc.) - Keep it practical — focus on rules that affect day-to-day development - Folder structure should extend from what already exists in the project, not replace it ### Step 3: Update DESCRIPTION.md If the resolved DESCRIPTION.md path exists, add or update an architecture-pointer section in resolved `language.artifacts`. Use the resolved architecture path from config, not the default path literal. ```markdown ## [Localized heading: Architecture] [Localized sentence in resolved artifacts language referencing the resolved architecture artifact path for detailed architecture guidelines.] [Localized label: Pattern]: [chosen pattern name] ``` ### Step 4: Update AGENTS.md If `AGENTS.md` exists in the project root, add the resolved architecture artifact path to the localized "AI Context Files" table in resolved `language.artifacts`: ```markdown | [resolved-architecture-path] | [Localized architecture artifact description in resolved artifacts language] | ``` Only add if the resolved architecture path is not already present. ### Step 5: Confirm Present the confirmation in resolved `language.ui` and report the resolved architecture path: ``` [Localized success heading in `language.ui`] [Localized pattern label in `language.ui`]: [chosen pattern] [Localized file label in `language.ui`]: [resolved architecture path] [Localized key-rules heading in `language.ui`]: - [rule 1] - [rule 2] - [rule 3] [Localized closing sentence in `language.ui` about workflow skills following these architecture guidelines.] ``` ## Artifact Ownership - Primary ownership: the resolved architecture artifact path (default: `.ai-factory/ARCHITECTURE.md`). - Respect config overrides: write to the resolved architecture path from `config.yaml` when provided. - Allowed companion updates: architecture pointer in the resolved DESCRIPTION path from `config.yaml`, architecture row in `AGENTS.md` context table. - Read-only context: roadmap, rules, research, and plan artifacts unless user explicitly requests otherwise. --- ## Knowledge Base Reference material for architecture evaluation and generation. This content informs the generation — it is NOT output directly. ### Decision Matrix | Factor | Layered | Clean Architecture | Modular Monolith | DDD | Microservices | |--------|---------|-------------------|-------------------|-----|---------------| | Team size | 1-5 | 1-15 | 5-30 | 5-30 | 20+ | | Domain complexity | Low | Medium-High | Medium-High | High | High | | Scale requirements | Low | Moderate | Moderate-High | Moderate-High | Very High | | Deploy independence | ❌ | ❌ | Partial | Partial | ✅ | | Initial velocity | ✅ Fast | Medium | ✅ Fast | Medium | ❌ Slow | | Operational complexity | ✅ Low | ✅ Low | ✅ Low | Medium | ❌ High | ### Quick Decision Guide ``` New project, small team? → Modular Monolith or Layered Complex business logic, many rules? → Clean Architecture Multiple subdomains, large team? → DDD Independent scaling + large org? → Microservices Simple CRUD app? → Layered Architecture Unclear requirements? → Start simple, refactor when patterns emerge ``` ### Clean Architecture **Core Principle:** Dependencies point inward. Inner layers know nothing about outer layers. ``` ┌─────────────────────────────────────────────────────────┐ │ Frameworks & Drivers │ │ ┌─────────────────────────────────────────────────┐ │ │ │ Interface Adapters │ │ │ │ ┌─────────────────────────────────────────┐ │ │ │ │ │ Application Layer │ │ │ │ │ │ ┌─────────────────────────────────┐ │ │ │ │ │ │ │ Domain Layer │ │ │ │ │ │ │ │ (Entities & Business Rules) │ │ │ │ │ │ │ └─────────────────────────────────┘ │ │ │ │ │ └─────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ ``` **Folder Structure (TypeScript example):** ``` src/ ├── domain/ # Core business logic (no dependencies) │ ├── entities/ │ ├── value-objects/ │ └── repositories/ # Interfaces only ├── application/ # Use cases (depends on domain) │ ├── use-cases/ │ └── services/ ├── infrastructure/ # External concerns (implements interfaces) │ ├── database/ │ ├── external/ │ └── config/ └── presentation/ # UI/API layer ├── api/ ├── controllers/ └── dto/ ``` **Dependency Rules:** - Domain → nothing (pure business logic) - Application → Domain only - Infrastructure → Application + Domain (implements interfaces) - Presentation → Application (calls use cases) ### Domain-Driven Design (DDD) **Core Principle:** Software structure mirrors the business domain. Bounded contexts define clear boundaries. **Strategic Patterns:** - Bounded Contexts: explicit boundaries around domain models - Context Mapping: how contexts communicate (Shared Kernel, Customer/Supplier, Anti-Corruption Layer) **Tactical Patterns:** - Entities: identity-based objects - Value Objects: immutable, equality by value - Aggregates: consistency boundaries (all invariants enforced through aggregate root) - Domain Events: communicate state changes between contexts **Folder Structure (TypeScript example):** ``` src/ ├── contexts/ │ ├── ordering/ │ │ ├── domain/ # Entities, VOs, events, repository interfaces │ │ ├── application/ # Use cases, command/query handlers │ │ ├── infrastructure/ # Repository implementations, external adapters │ │ └── api/ # HTTP handlers, DTOs │ ├── inventory/ │ │ └── ... │ └── shipping/ │ └── ... └── shared/ └── kernel/ # Shared base classes, interfaces ``` ### Microservices **When to Use:** - Large teams needing independent deployment - Different scaling requirements per service - Polyglot persistence needs **When NOT to Use:** - Small team (< 10 people) - Unclear domain boundaries - Startups exploring product-market fit **Communication Patterns:** - Synchronous (HTTP/gRPC): queries, real-time validation - Asynchronous (Events/Messages): side effects, eventual consistency **Data Patterns:** - Database per Service - Saga Pattern for distributed transactions ### Modular Monolith **Core Principle:** Single deployment unit with strong module boundaries. Best of both worlds — simple ops, future extraction ready. **Folder Structure (TypeScript example):** ``` src/ ├── modules/ │ ├── users/ │ │ ├── api/ # HTTP handlers │ │ ├── domain/ # Business logic │ │ ├── infra/ # Database, external │ │ └── index.ts # Public API only │ ├── orders/ │ │ └── ... │ └── payments/ │ └── ... ├── shared/ # Truly shared code │ ├── kernel/ │ └── utils/ └── main.ts # Composition root ``` **Module Communication Rules:** - Modules expose explicit public API via index file - Other modules use ONLY the public API - Never reach into module internals ### Layered Architecture **Core Principle:** Separate concerns into horizontal layers. Each layer only depends on the layer directly below it. **Folder Structure (TypeScript example):** ``` src/ ├── routes/ # Presentation layer (HTTP handlers) ├── controllers/ # Request/response handling ├── services/ # Business logic layer ├── models/ # Data models ├── repositories/ # Data access layer └── utils/ # Cross-cutting utilities ``` **Dependency Rules:** - Routes → Controllers → Services → Repositories → Database - No skipping layers (routes should not call repositories directly)