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:

Layer	Examples
Language	Rust, TypeScript, Python, Go
Frontend Framework	React, Vue, Svelte, SolidJS
Backend Framework	Axum, Actix, Express, FastAPI
Database	PostgreSQL, SQLite, MongoDB
ORM/Query Builder	Diesel, SQLx, Prisma, Drizzle
Authentication	JWT, Sessions, OAuth providers
Deployment	Docker, Serverless, VPS
Testing	Built-in, Jest, Pytest, Vitest

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.