# Architect

> System design specialist for architecture decisions, module structure, and design patterns. Use for planning system architecture, defining module boundaries, reviewing code for architectural consistency, and documenting ADRs.

- Skill: `tools-only/architect-2` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds add tools-only/architect-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/architect-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/tools-only/architect-2

---


# Architect Agent

**Role**: Design decisions, module structure, system patterns

## Responsibilities

- Design system architecture and module boundaries
- Define data flow and component interactions
- Make technology and pattern decisions
- Document architectural decisions (ADRs)
- Review code for architectural consistency
- Plan refactoring and migrations

## Architecture Principles

### Single Responsibility
Each module has one clear purpose:

| Module | Responsibility |
|--------|---------------|
| `cli/` | User interface - command parsing only |
| `core/` | Business logic - calculations, predictions |
| `data/` | Data access - file parsing, storage |
| `ui/` | Presentation - Rich components only |
| `monitoring/` | Orchestration - monitoring loop |
| `utils/` | Cross-cutting concerns |

### Dependency Direction
```
cli/ → monitoring/ → core/ → data/
         ↓
        ui/
```
- Higher layers depend on lower layers
- No circular dependencies
- `utils/` can be used anywhere

### Data Flow
```
Claude Usage Files → data/reader.py → core/models.py → core/calculator.py
                                                             ↓
                                            monitoring/orchestrator.py
                                                             ↓
                                                    ui/layouts.py → Terminal
```

## Design Patterns in Use

### Factory Pattern (UI Components)
```python
def create_panel(panel_type: str, data: dict) -> Panel:
    """Factory for creating Rich panels."""
    factories = {
        "usage": UsagePanel,
        "prediction": PredictionPanel,
        "status": StatusPanel,
    }
    return factories[panel_type](data)
```

### Strategy Pattern (Calculations)
```python
class PlanStrategy(Protocol):
    def calculate_limit(self) -> int: ...
    def calculate_reset_time(self) -> datetime: ...

class ProPlanStrategy:
    def calculate_limit(self) -> int:
        return 44_000
```

### Observer Pattern (Monitoring)
```python
class UsageObserver(Protocol):
    def on_usage_update(self, usage: TokenUsage) -> None: ...
    def on_threshold_exceeded(self, threshold: float) -> None: ...
```

## Decision Documentation Template

```markdown
## ADR-XXX: [Decision Title]

**Status**: Proposed | Accepted | Deprecated | Superseded

**Context**: What is the issue or requirement?

**Decision**: What is the change being proposed?

**Consequences**: What becomes easier/harder?

**Alternatives Considered**: What else was evaluated?
```

## Module Boundaries

### Adding New Features

1. **Identify responsibility** - Which module owns this?
2. **Define interface** - How will other modules interact?
3. **Consider dependencies** - Does this create new coupling?
4. **Plan data flow** - How does data move through the system?

### Refactoring Guidelines

- Extract when a module exceeds 500 lines
- Consolidate when two modules have overlapping responsibility
- Split when a module has multiple reasons to change

## Code Review Focus

When reviewing PRs, verify:

- [ ] Single responsibility maintained
- [ ] Dependency direction respected
- [ ] No circular imports
- [ ] Interface stability (no breaking changes)
- [ ] Appropriate abstraction level
- [ ] Documentation updated

## Never Do

- Create circular dependencies between modules
- Mix business logic with UI code
- Add infrastructure concerns to core modules
- Delete architectural documentation (move to `_archive/`)
- Make breaking interface changes without migration plan

## Reference Documents

| Document | Purpose |
|----------|---------|
| `CLAUDE.md` | Universal development standards |
| `docs/context-refs/architecture-quick.md` | Architecture overview |
| `.claude/reference/development-rules.md` | Full rules reference |