Architecture · git:20260714.061716b · 2026-07-14 · sha256 009a02029989b90b
Architecture git:20260714.061716bA
Immutable. This exact content never changes and is served at /api/v1/blob/009a02029989b90b.
---
name: Architecture
description: Provides architectural design patterns, system structure guidance, and component organization best practices.
disable-model-invocation: true
---
# NXTG-Forge System Architecture
**Purpose**: Comprehensive understanding of NXTG-Forge's Clean Architecture implementation, design patterns, and component interactions.
**When to Use**: Any task involving system design, new features, refactoring, or understanding component relationships.
---
## System Overview
NXTG-Forge is a next-generation CLI tool for project scaffolding that implements Clean Architecture principles with specialized AI agent orchestration.
```
┌─────────────────────────────────────────────────────────────┐
│ NXTG-Forge Architecture │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ │
│ │ CLI │◄──────────────────►│ Hooks │ │
│ │ Interface │ │ System │ │
│ └──────┬───────┘ └──────────────┘ │
│ │ │
│ ┌──────▼───────────────────────────────────┐ │
│ │ Application Layer │ │
│ │ (Use Cases, Orchestration) │ │
│ └──────┬───────────────────────────────────┘ │
│ │ │
│ ┌──────▼───────────┐ ┌───────────────┐ │
│ │ Domain Layer │ │ Agent System │ │
│ │ (Pure Business) │◄──────►│ Orchestrator │ │
│ └──────┬───────────┘ └───────┬───────┘ │
│ │ │ │
│ ┌──────▼────────────────────────────▼──────┐ │
│ │ Infrastructure Layer │ │
│ │ (File System, Templates, State) │ │
│ └──────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
---
## Clean Architecture Principles
### Core Tenets
1. **Independence of Frameworks**: Business logic doesn't depend on external libraries
2. **Testability**: Business rules can be tested without UI, database, or external services
3. **Independence of UI**: UI can change without changing business rules
4. **Independence of Database**: Business rules not bound to database
5. **Independence of External Agencies**: Business rules don't know about the outside world
### Dependency Rule
**Dependencies point inward**: Outer layers can depend on inner layers, never the reverse.
```
┌───────────────────────────────────┐
│ Interface Layer (CLI) │ ─┐
├───────────────────────────────────┤ │
│ Infrastructure Layer (File I/O) │ ─┼─► Dependencies flow inward
├───────────────────────────────────┤ │
│ Application Layer (Use Cases) │ ─┤
├───────────────────────────────────┤ │
│ Domain Layer (Business Logic) │ ◄┘
└───────────────────────────────────┘
↑ No outward dependencies
```
---
## Layer Structure
### 1. Domain Layer (`forge/domain/`)
**Purpose**: Pure business logic, completely independent of external concerns.
**Components**: Entities (immutable, identity-based), Value Objects (attribute-defined), Domain Services (cross-entity logic)
**Rules**:
- No external dependencies (no imports from outer layers)
- All functions should be pure where possible
- Immutable data structures (`frozen=True`)
- Business rules live here and only here
→ See `patterns.md` §Domain Layer Examples for code
---
### 2. Application Layer (`forge/application/`)
**Purpose**: Orchestrate domain objects to fulfill use cases.
**Components**: Use Cases (high-level workflows), Application Services (multi-use-case coordination), DTOs (inter-layer data)
**Rules**:
- Orchestrates domain layer — no business logic of its own
- Handles transaction boundaries
- Converts between domain and external representations
→ See `patterns.md` §Application Layer Examples for code
---
### 3. Infrastructure Layer (`forge/infrastructure/`)
**Purpose**: Implement interfaces defined by inner layers; handle all I/O.
**Components**: Repository implementations, File system access (Jinja2 rendering), State persistence (JSON)
**Rules**:
- Implements domain interfaces
- All I/O happens here
- No domain logic
- External library usage concentrated here
→ See `patterns.md` §Infrastructure Layer Examples for code
---
### 4. Interface Layer (`forge/interface/`)
**Purpose**: User interaction points (CLI via Click).
**Rules**:
- Thin layer — delegates immediately to application
- Input validation and output formatting only
- No business logic
→ See `patterns.md` §Interface Layer Examples for code
---
## Agent System Architecture
### Agent Types
| Agent | Specialty |
|---|---|
| `LEAD_ARCHITECT` | System design and architectural decisions |
| `BACKEND_MASTER` | API, backend, database |
| `CLI_ARTISAN` | CLI commands and interfaces |
| `PLATFORM_BUILDER` | Platform and infrastructure |
| `INTEGRATION_SPECIALIST` | Third-party integrations |
| `QA_SENTINEL` | Testing and quality |
### Orchestration Model
Tasks assigned via keyword matching in task descriptions. `AgentOrchestrator` selects agent type; `TaskDispatcher` manages queue, async execution, and history tracking.
Agent configuration lives in `.claude/config.json` (`agents.available_agents[]`). Max 3 parallel agents by default; handoff timeout 300s.
→ See `patterns.md` §Agent System Examples for code
---
## Hook System Design
### Hook Lifecycle
```
Task/Operation Start
↓
[pre-task.sh] ← Environment validation
↓
[Task Execution]
↓
[on-file-change.sh] ← After each file write
↓
[on-error.sh] ← If error occurs
↓
[post-task.sh] ← Quality checks
↓
Task Complete
```
### Hook Types
| Hook | Purpose |
|---|---|
| `pre-task.sh` | Validate Python version, venv, deps, DB connection; warn on uncommitted changes |
| `post-task.sh` | Run black, ruff, mypy, tests + coverage, bandit, doc updates |
| `on-error.sh` | Capture error details, log system state, record git changes, create debug report |
| `on-file-change.sh` | Quick format, syntax check, fast type check after file modification |
Hooks receive context via env vars (`NXTG_PROJECT_ROOT`, `NXTG_TASK_DESCRIPTION`, `NXTG_AGENT_TYPE`, `NXTG_CONFIG_FILE`).
→ See `patterns.md` §Hook Configuration Examples
---
## State Management
### State Architecture
```
ProjectState (Immutable frozen dataclass)
├── project_id, name, template, variables
├── status: ProjectStatus
└── created_at: datetime
SessionState (In-Memory)
├── agent_context: dict
├── progress: float
└── errors: list
StateManager (Persistence Interface)
├── save(state)
├── load() → state
└── checkpoint(desc)
```
### State Transitions
```
INITIALIZING → READY
READY → GENERATING
GENERATING → COMPLETED | ERROR
COMPLETED → ARCHIVED
ERROR → READY (after fix)
```
State persisted to `.nxtg-forge/state.json`. Checkpoints tracked with timestamp and description.
→ See `patterns.md` §State Management Examples for code
---
## Design Patterns — Index
| Pattern | Purpose | Key Class |
|---|---|---|
| Repository | Abstract data access; domain interface + infra impl | `TemplateRepository` / `FileTemplateRepository` |
| Strategy | Interchangeable algorithms for same operation | `TemplateSelectionStrategy` (Interactive / Config-based) |
| Observer | Decouple event producers from consumers | `HookNotifier` + `HookObserver` |
| Command | Encapsulate operations as executable objects | `GenerateProjectCommand` |
| DI Container | Decouple construction from use; singleton vs transient | `Container` in `infrastructure/di_container.py` |
→ See `patterns.md` §Design Pattern Code Examples for implementations
---
## Quality Attributes
| Attribute | Approach |
|---|---|
| **Testability** | Pure domain functions (no mocks needed); injectable deps via constructor; mock-friendly interfaces |
| **Maintainability** | Clear layer boundaries; SRP; ADRs for decisions |
| **Extensibility** | Template plugins via config; new agents via config; hook system for custom behavior |
| **Performance** | Lazy template loading; in-memory caching of parsed templates; parallel file generation |
---
## Architecture Decision Records — Summary
| ADR | Decision | Key Trade-offs |
|---|---|---|
| ADR-001 | Clean Architecture adoption | ✅ Testability, clear boundaries ⚠️ Initial complexity, learning curve |
| ADR-002 | Agent-based generation | ✅ Parallelism, specialized expertise ⚠️ Coordination overhead, state sync |
| ADR-003 | Immutable state (frozen dataclasses) | ✅ Predictability, thread-safety ⚠️ More object creation |
→ See `adr-templates.md` for full ADR records and blank template
---
## Detailed References
| File | Content |
|---|---|
| `patterns.md` | Full code examples: all four layers, agent system, hooks, state management, design patterns, DI container |
| `adr-templates.md` | Full ADR-001/002/003 records; blank ADR template for new decisions |
## Related Skills
- [Coding Standards](../coding-standards/SKILL.md) — Implementation patterns and conventions
- [Domain Knowledge](../domain-knowledge/SKILL.md) — NXTG-Forge business concepts
- [Testing Strategy](../testing-strategy/SKILL.md) — How to test this architecture
---
*Last Updated: 2026-01-06 | Version: 1.0.0*