Architect Skill

Research, evaluate, and decide on technology stack and system architecture based on project requirements.

Workspace Mode Note

When running in workspace mode, all paths are relative to .aha-loop/ directory:

• Vision analysis: .aha-loop/project.vision-analysis.md
• Architecture output: .aha-loop/project.architecture.md

The orchestrator will provide the actual paths in the prompt context.

The Job

1. Read project.vision-analysis.md for requirements
2. Research candidate technologies for each layer
3. Evaluate and compare options
4. Make decisions with documented rationale
5. Design system architecture
6. Output project.architecture.md

Core Principles

1. Prefer Latest Stable Versions

Always use the latest stable version of libraries unless there's a specific reason not to.

## Version Selection Process

1. Query official source for latest version:
   - Rust: crates.io API or `cargo search`
   - Node: npmjs.com or `npm view [pkg] version`
   - Python: pypi.org or `pip index versions`

2. Check release date and stability:
   - Released > 2 weeks ago (not bleeding edge)
   - No critical issues in GitHub issues
   - Changelog shows no breaking changes from common patterns

3. Document the version and why:
   - Record in project.architecture.md
   - Add to knowledge/project/decisions.md

2. Consider Long-term Maintenance

• Active community and regular updates
• Good documentation
• Large ecosystem of plugins/extensions
• Backed by reputable organization or strong community

3. Evaluate Total Cost

• Learning curve for the team/AI
• Bundle size / binary size
• Runtime performance
• Development velocity

Research Process

Step 1: Identify Technology Layers

Based on project type, identify which layers need decisions:

Step 2: Research Each Layer

For each layer requiring a decision:

1. Identify 2-4 candidates - Don't over-research
2. Fetch source code if needed for deep understanding
3. Check latest versions - Use web search or package registry
4. Read documentation - Understand core concepts
5. Compare tradeoffs - Performance, DX, ecosystem

Step 3: Use Structured Comparison

## [Layer Name] Decision

### Candidates

| Criterion | Option A | Option B | Option C |
|-----------|----------|----------|----------|
| Latest Version | v1.2.3 | v2.0.0 | v0.9.0 |
| Release Date | 2026-01-15 | 2026-01-20 | 2025-12-01 |
| GitHub Stars | 45k | 30k | 15k |
| Bundle Size | 50kb | 80kb | 30kb |
| Learning Curve | Medium | Low | High |
| Documentation | Excellent | Good | Fair |
| TypeScript Support | Native | Via types | Partial |
| Community Activity | Very Active | Active | Moderate |

### Decision: [Option B]

### Rationale
- [Reason 1]
- [Reason 2]
- [Reason 3]

### Tradeoffs Accepted
- [What we're giving up]
- [Mitigation strategy if any]

Step 4: Check Compatibility

Before finalizing:

• Verify all chosen technologies work together
• Check for known integration issues
• Ensure versions are compatible
• Test with a minimal proof-of-concept if uncertain

Version Research Commands

Rust (crates.io)

# Get latest version
curl -s "https://crates.io/api/v1/crates/tokio" | jq '.crate.max_stable_version'

# Or use cargo
cargo search tokio --limit 1

Node.js (npm)

# Get latest version
npm view react version

# Get all versions
npm view react versions --json

Check GitHub for Activity

# Using gh CLI
gh api repos/tokio-rs/tokio --jq '.pushed_at, .stargazers_count'

Architecture Design

After technology decisions, design the architecture:

1. Component Diagram

## System Components

[Component A] --> [Component B] --> [Component C]
       |                               |
       v                               v
  [Database]                    [External API]

2. Data Flow

Document how data flows through the system:

• User inputs
• Processing steps
• Storage points
• Output paths

3. Directory Structure

Propose the project structure:

project/
├── src/
│   ├── main.rs
│   ├── api/
│   ├── db/
│   └── ...
├── tests/
├── Cargo.toml
└── ...

4. Key Patterns

Document architectural patterns to follow:

• Error handling approach
• Logging strategy
• Configuration management
• Testing approach

Output: project.architecture.md

# Project Architecture

**Generated:** [timestamp]
**Based on:** project.vision-analysis.md

## Technology Stack

### Core Technologies

| Layer | Technology | Version | Rationale |
|-------|------------|---------|-----------|
| Language | Rust | 1.75 | Performance, safety |
| Web Framework | Axum | 0.7.4 | Ergonomic, async |
| Database | SQLite | 3.45 | Simple, embedded |
| ORM | SQLx | 0.7.3 | Compile-time checks |

### Development Tools

| Tool | Version | Purpose |
|------|---------|---------|
| cargo-watch | 8.5.2 | Auto-rebuild |
| sqlx-cli | 0.7.3 | Migrations |

## Architecture Decisions

### ADR-001: [Decision Title]

**Context:** [Why this decision was needed]
**Decision:** [What was decided]
**Rationale:** [Why this option]
**Consequences:** [Impact of decision]

### ADR-002: ...

## System Design

### Component Overview

[Diagram or description]

### Data Flow

[How data moves through system]

### Directory Structure

[Proposed structure]

## Key Patterns

### Error Handling
[Approach]

### Configuration
[Approach]

### Testing Strategy
[Approach]

## Dependencies

### Production Dependencies

```toml
[dependencies]
axum = "0.7.4"
tokio = { version = "1.35", features = ["full"] }
sqlx = { version = "0.7.3", features = ["sqlite", "runtime-tokio"] }

Development Dependencies

[dev-dependencies]

Security Considerations

• [Security item 1]
• [Security item 2]

Performance Considerations

• [Performance item 1]
• [Performance item 2]

Deployment Strategy

[How the project will be deployed]

Next Steps

1. Initialize project structure
2. Set up CI/CD
3. Begin roadmap planning

---

## Integration with Orchestrator

After architecture design:

1. Save `project.architecture.md` to project root
2. Update `knowledge/project/decisions.md` with ADRs
3. Signal completion to orchestrator
4. Roadmap Skill uses architecture as input

---

## Checklist

Before completing architecture:

- [ ] All technology layers evaluated
- [ ] Latest stable versions verified for each choice
- [ ] Compatibility between choices confirmed
- [ ] Decisions documented with rationale
- [ ] Directory structure proposed
- [ ] Key patterns defined
- [ ] Dependencies listed with versions
- [ ] ADRs recorded in knowledge/project/decisions.md
- [ ] Architecture saved to `project.architecture.md`

---

## Example: Web App Architecture

**Input:** Vision analysis showing PWA finance tracker

**Output:**

```markdown
# Project Architecture

## Technology Stack

### Core Technologies

| Layer | Technology | Version | Rationale |
|-------|------------|---------|-----------|
| Language | TypeScript | 5.3.3 | Type safety, ecosystem |
| Framework | SvelteKit | 2.5.0 | Fast, simple, SSR+SPA |
| Styling | Tailwind CSS | 3.4.1 | Utility-first, fast |
| Database | IndexedDB (Dexie) | 4.0.1 | Offline-first PWA |
| Build | Vite | 5.0.12 | Fast, modern |

### PWA Stack

| Component | Technology | Version |
|-----------|------------|---------|
| Service Worker | Workbox | 7.0.0 |
| Manifest | Vite PWA Plugin | 0.17.4 |

## Architecture Decisions

### ADR-001: SvelteKit over React/Next.js

**Context:** Need a modern frontend framework for PWA
**Decision:** Use SvelteKit 2.x
**Rationale:**
- Smaller bundle size (critical for PWA)
- Built-in SSR and static generation
- Simpler mental model than React
- Excellent TypeScript support
**Consequences:** Smaller community than React, but sufficient for this project.

### ADR-002: Dexie for IndexedDB

**Context:** Need offline data storage
**Decision:** Use Dexie.js 4.x wrapper for IndexedDB
**Rationale:**
- Promise-based API
- Excellent TypeScript support
- Reactive queries
- Well-maintained
**Consequences:** Additional 30kb bundle, but worth the DX improvement.