Architecture Skill

Version: 3.0 Source: Architecture Principles + Project Structure Profiles

How to structure a project — both logically (module design, dependency flow) and physically (folder layout, naming, type-specific conventions).

Scope and Boundaries

This skill covers: Module design, dependency flow, folder structure, naming conventions, and project-type-specific layouts.

This skill does NOT cover: Code quality within files (see code-quality), documentation standards (see documentation), or build/deploy configuration.

Relationship to other skills:

• Works alongside code-quality (file-level conventions) and documentation (docs standards)
• Consumed by clean-team :audit command (with focus: structure)
• Referenced by clean-team, implement-team, and diagnose-team agents

North Star

Goal: Small changes stay local.

A typical feature should touch 1-2 modules, ship quickly, and not require coordinated edits across the system. If you find yourself editing 5+ files across multiple layers for a simple change, that’s a design smell.

Core Principles

1. Explicit Over Magic

Prefer readable wiring over convention-heavy frameworks. When someone reads your code, the control flow should be obvious. No @AutoInject() decorators that hide what depends on what — use explicit constructor parameters.

2. Boundaries Are Sacred

Modules communicate only through contracts (APIs, props, events). No reaching into another module’s internals. Import from the module’s public API, never from internal files.

3. Own Your Data

Each module owns its schema/state. Other modules read via APIs or props, never direct access. If OrderModule needs user data, it calls UserModule.getUserById() — it doesn’t query the users table directly.

4. Optimize for Refactoring

If code is hard to move or rename, it’s a design smell. Loose coupling enables safe refactoring.

The 3 Layers

01-presentation/  →  02-logic/  →  03-data/

Valid Dependency Flow

Presentation → Logic → Data ✅
Data → Logic ❌ (blocked)
Logic → Presentation ❌ (blocked)
Presentation → Data ❌ (blocked — no layer skipping)

Module Boundaries

A module is a cohesive unit with a clear public API, hidden implementation, and defined dependencies.

Module Rules

Single Entry Point: Each module exposes its API through an index file. External imports MUST go through it.

No Circular Dependencies: Modules cannot depend on each other in a cycle. Break cycles by extracting shared code, using events, or introducing an interface.

Own Your Data: Each module owns its data exclusively. Cross-module data is accessed via APIs, never direct DB queries.

Coupling Guidelines

Full details: references/module-boundaries.md — Module structure, boundary rules, communication patterns, coupling levels, refactoring guidance

Folder Structure

A well-organized project isn’t just tidy — it’s a project where you never have to ask “where does this go?” or “where would I find that?” The structure itself answers those questions. When folders mirror how you think about the project, navigation becomes intuitive rather than a search exercise. You find things where you expect them to be, on the first try.

This matters even more when AI is involved. AI has no memory between sessions — it can’t learn your project’s layout over time the way a human teammate would. Every session starts fresh. A clear, predictable structure means the AI spends less time searching and more time doing useful work. Descriptive folder names, consistent conventions, and logical grouping are context that the AI reads for free on every interaction.

The goal: any file should be findable in 2-3 navigation steps based on intuition alone. If you have to search, the structure failed.

Organize by Feature Within Tiers

For web projects using 3-tier architecture, organize by feature WITHIN each tier — don’t scatter a single feature across global models/, services/, controllers/ directories.

Within 02-logic/:
Prefer:                          Avoid:
02-logic/                        02-logic/
  users/                           models/
    user.model.ts                    user.model.ts
    user.service.ts                  order.model.ts
  orders/                          services/
    ...                              user.service.ts
                                     order.service.ts

Feature-based grouping keeps related code together within each tier. Tiers enforce dependency flow (presentation → logic → data), while feature folders enforce cohesion within each tier. These are complementary, not contradictory.

For non-web projects (CLI tools, libraries, scripts) that don’t use 3-tier architecture, apply feature-based grouping at the project root level.

Universal Structural Principles

These apply to every project regardless of type.

Naming Consistency — Pick one casing convention per category and apply it everywhere. All components PascalCase, all utilities camelCase, all configs kebab-case. Consistency makes things findable — when you know the convention, you can predict the file name before you look.

Logical Grouping — Related files live together. If you change one, you’ll likely change the others. Co-locate by default. Only separate when there’s a clear benefit. The test for grouping: “If I’m working on X, what else will I need open?”

Reasonable Depth — No more than 4 levels from root to file. Every level of nesting must earn its place. If a folder contains only one subfolder containing one file — flatten it. Deep nesting isn’t organization, it’s a scavenger hunt.

Clear Entry Point — Someone opening the project for the first time should know where to start within 10 seconds. Root README explains what the project is. The main entry file is named conventionally (index, main, app). Top-level folders tell the story of what the project is.

Clean Root — The project root should contain only what must be there — entry points, top-level config, and the folders that define the project’s structure. Config files that must live at root (.gitignore, package.json, tsconfig.json) get a pass — stray scripts, utilities, and one-off files do not. When in doubt, move it deeper. The root is the first impression.

Self-Documenting Names — Folder names describe what’s inside, not how it’s used. formatters/, validators/, parsers/ are clear. utils/, helpers/, misc/ are dumping grounds. If a folder has more than 10 files with no shared theme, split by what the files actually do.

Project Type Profiles

Type-specific folder structures, naming conventions, and red flags. Each profile is a self-contained reference.

Detection Decision Tree

Does the project contain...

  ├─ package.json + .tsx/.jsx/.css/.html files?
  │  └─ YES → Load references/web.md
  │
  ├─ Assets/ + .cs scripts + .unity scene files?
  │  ├─ VRChat SDK present? (Packages/com.vrchat.*, VRCSDK3, UdonSharp)
  │  │  └─ YES → Load references/vrchat.md (overrides Unity)
  │  └─ No VRC SDK
  │     └─ Load references/unity.md
  │
  ├─ .blend files + texture images?
  │  └─ YES → Load references/blender.md
  │
  ├─ .tf files / cdk.json / template.yaml?
  │  └─ YES → Load references/data-iac.md
  │
  └─ None of the above?
     └─ Use Universal Structural Principles above

Priority rule: When multiple profiles match, use the most specific. VRChat overrides Unity. A project with both application code and IaC should use the application profile for the app and reference data-iac for the infrastructure portion.

Available Profiles

How to Use

1. Detect the project type using the decision tree above
2. Load the matching profile from references/
3. Compare the actual structure against the expected layout
4. Evaluate using the checklist in assets/structure-evaluation-checklist.md
5. Flag deviations as findings — prioritize red flags highest

Adding a New Profile

1. Create references/<type>.md following the standard template:
   • Why This Structure Matters — problem, benefit, cost of ignoring
   • Detection — file patterns that identify this project type
   • Expected Structure — annotated directory tree with principle comments
   • Naming Conventions — table of type/convention/example
   • Red Flags — 3-column table: Flag | Root Cause | Fix
   • When to Reconsider — symptom → problem → action table
2. Add a row to the Available Profiles table above
3. Add a branch to the Detection Decision Tree
4. Add a type-specific section to assets/structure-evaluation-checklist.md

Pattern Selection

Default to simplicity: Function → Module → Class → Pattern

Full catalog: references/design-patterns.md — Factory, Builder, Adapter, Facade, Decorator, Strategy, Observer, Command, Repository, Result Type

Testing Strategy

Heavy unit tests, moderate integration, minimal E2E. E2E sprawl leads to brittle, slow test suites. Contract tests recommended for API boundaries.

Anti-Patterns

Code Architecture

Project Structure

When to Extract

Start with a modular monolith (single deployable, clean internal boundaries).

Extract to separate services only when:

Don’t extract for “cleanliness” — that adds operational complexity without benefit.

Observability Basics

Structured Logging: JSON, not string concatenation. Include context ({ userId, timestamp }), not messages ('User ' + userId + ' logged in').

Correlation IDs: Track requests across async operations.

Error Boundaries: Catch and report, don’t swallow silently.

Decision Records

For significant architectural choices, document: Context (problem), Decision (what we chose), Alternatives (what else we considered), Consequences (trade-offs).

Location: Documentation/decisions/

Template: assets/decision-record-template.md

Scaling Principles

Red Flags

Stop and reconsider when you see:

Enforced Rules

These rules are deterministically checked by check.js (clean-team). When updating these standards, update the corresponding check.js rules to match — and vice versa.

References

• references/module-boundaries.md — Module structure, boundary rules, communication patterns
• references/design-patterns.md — Factory, Repository, Adapter, Strategy, Observer, etc.
• references/migration-patterns.md — Strangler Fig, Branch by Abstraction, Parallel Implementations
• references/web.md — Web (React/Node) project structure profile
• references/unity.md — Unity project structure profile
• references/vrchat.md — VRChat project structure profile (extends Unity)
• references/blender.md — Blender project structure profile
• references/data-iac.md — Data/IaC (AWS) project structure profile

Assets

• assets/architecture-checklist.md — Full architecture review checklist
• assets/structure-evaluation-checklist.md — Project structure evaluation checklist (universal + per-type)
• assets/decision-record-template.md — ADR template

Scripts

• scripts/analyze_dependencies.py — Map circular dependencies and detect layer violations