Architecture Gen

Step 2 — File & Folder Structure

Produce a complete tree of all files that will exist in the repository, including:

• Source files (with meaning of each)
• Test files
• Config files (tsconfig.json, vitest.config.ts, etc.)
• CI/CD files
• Documentation files
• Community health files

Use standard tree notation. Mark files as [generated] if they are output of build tools and should be in .gitignore.

Step 3 — Core API Surface

Define the main exports of the library/tool. For each:

• Function/class name — in the naming convention of the ecosystem (camelCase for JS, snake_case for Python)
• TypeScript signature or Python type hint
• One-sentence description of what it does
• Example usage (2–4 lines of code)

The API surface for a v1.0 should have at most 8–10 public exports. Push back if the user wants more — this is a feature, not a bug.

Step 4 — Data Models

For any data structures the library produces or consumes:

• Define as TypeScript interface or Python @dataclass / TypedDict
• Include field names, types, and inline comments
• Identify which fields are required vs optional

Step 5 — Dependency Analysis

List all runtime (non-dev) dependencies with:

• Package name
• Version range (use ^ for semver, be conservative)
• Reason it's needed
• Last publish date check (use npm-check tool)
• Alternative if this dep becomes unmaintained

Target: 0–3 runtime dependencies for a library. More is a red flag that needs justification.

Step 6 — Architecture Decisions Record (ADR)

For each significant technical choice (especially any that seem opinionated), write one ADR entry:

• Decision: What was chosen
• Context: Why this decision needed to be made
• Rationale: Why this option over alternatives
• Consequences: What tradeoffs this introduces

Output Format

## Architecture: [project-name]

### Tech Stack
| Component | Choice | Justification |
|-----------|--------|---------------|
| Runtime | Node.js 22+ | ... |
| Build | tsup | ... |
| Test | Vitest | ... |
| Types | TypeScript 5.x | ... |
| Lint | ESLint + Prettier | ... |
| CI | GitHub Actions | ... |

---

### File Structure
\`\`\`
project-name/
├── src/
│   ├── index.ts          # Main entry point & exports
│   ├── core.ts           # Core logic
│   └── types.ts          # Type definitions
├── test/
│   └── index.test.ts     # Tests  
├── .github/
│   └── workflows/
│       └── ci.yml        # CI pipeline
├── .gitignore
├── package.json
├── tsconfig.json
├── vitest.config.ts
├── README.md
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE
\`\`\`

---

### Core API

\`\`\`typescript
// Main export
export function functionName(input: InputType, options?: Options): OutputType

// Type definitions
export interface InputType { ... }
export interface Options { ... }
export interface OutputType { ... }
\`\`\`

**Usage example:**
\`\`\`typescript
import { functionName } from 'project-name';
const result = functionName({ ... });
\`\`\`

---

### Data Models

\`\`\`typescript
export interface ModelName {
  /** Required: description */
  field: string;
  /** Optional: description */
  optionalField?: number;
}
\`\`\`

---

### Dependencies

| Package | Version | Purpose | Last Updated |
|---------|---------|---------|--------------|
| dep-name | ^1.2.0 | [purpose] | [date] |

**Dev dependencies:** (list)

---

### Architecture Decisions

#### ADR-001: [Decision Title]
- **Decision**: ...
- **Context**: ...  
- **Rationale**: ...
- **Consequences**: ...

Quality Bar

A good architecture output is one where a developer can open a blank terminal and know exactly what to type next. If the file tree doesn't account for every file that will exist on project initialization, it's incomplete.