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

Read project.vision-analysis.md for requirements
Research candidate technologies for each layer
Evaluate and compare options
Make decisions with documented rationale
Design system architecture
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:

Identify 2-4 candidates - Don't over-research
Fetch source code if needed for deep understanding
Check latest versions - Use web search or package registry
Read documentation - Understand core concepts
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

Initialize project structure
Set up CI/CD
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.