Architecture Skill

Read .hackathon/IDEA-FINAL.md first. This is the source of truth for what we're building.
Read .hackathon/STATE.md for team composition.

Hard gate: IDEA-FINAL.md must exist and be locked.

Architecture Process

Step 1: Component Identification

From the final idea, identify the major system components. Think in terms of:

• Frontend: What are the major pages/views?
• Backend: What are the major API domains?
• AI/ML: What processing pipeline(s) exist?
• Data: What's stored, where, how?
• External: What third-party services are involved?

Step 2: Component Map

Draw the component map in text/ASCII or describe it clearly:

[Frontend (React/Next)]
    ├── Upload Page
    ├── Processing View
    ├── Results Dashboard
    └── Form Pre-fill View
         │
         ▼
[API Layer (Hono)]
    ├── /api/documents    → Document CRUD + upload
    ├── /api/process      → OCR + keyword processing
    ├── /api/extract      → Field extraction
    └── /api/templates    → Form templates
         │
         ▼
[AI Processing Layer]
    ├── OCR Engine (Tesseract / Cloud Vision)
    ├── Keyword Scanner (string matching + AI classification)
    └── Field Extractor (Claude API for intelligent extraction)
         │
         ▼
[Data Layer]
    ├── Document Store (filesystem or S3)
    └── Metadata DB (SQLite / Postgres)

Step 3: Define the Contracts

This is the critical step for parallel development.

API Routes: For every API endpoint, define:

• HTTP method and path
• Request shape (params, query, body)
• Response shape (success and error)
• Behavior description

Write these to .hackathon/contracts/api-routes.md using the format defined in Section 6 (Contract System).

Shared Types: Define TypeScript interfaces for every domain entity and every API request/response. Write to .hackathon/contracts/shared-types.ts.

Data Models: Define the data layer schema. Write to .hackathon/contracts/data-models.md.

Step 4: Integration Points

For each place where two components connect, explicitly document:

• Who produces data, who consumes it
• The format of the data
• Error handling expectations
• What happens if the upstream component isn't ready yet (mock strategy)

Step 5: Developer Boundary Lines

Given the team in STATE.md, suggest how to split the architecture between developers:

• What can be built independently?
• What requires coordination?
• Where are the "handoff points" where one dev's output becomes another's input?
• What shared utilities need to be built first?

Output

Write to .hackathon/ARCHITECTURE.md:

---
owner: [lead dev]
status: draft
created-at: [timestamp]
last-modified: [timestamp]
phase: architect
---

# System Architecture

## Overview
[2-3 sentence summary of the architecture]

## Component Map
[Text diagram]

## Components
### [Component Name]
- Responsibility: [what it does]
- Technology: [what it's built with]
- Inputs: [what it receives]
- Outputs: [what it produces]
- Owner: [which dev]

[Repeat for each component]

## Integration Points
[From Step 4]

## Developer Boundaries
[From Step 5]

## Open Technical Questions
[Anything that needs investigation during scaffold]

Also create/update:

• .hackathon/contracts/api-routes.md
• .hackathon/contracts/shared-types.ts
• .hackathon/contracts/data-models.md

Update STATE.md, log to changelog.

NOTE: The architect phase can run in parallel with stack since architecture is somewhat independent of specific framework choices. However, scaffold requires both to be complete.