Generates a complete technical architecture for an open-source project: recommended tech stack, full file/folder structure, core API surface, data models, and dependency analysis.
You receive the validated idea and recommended project name from idea-validator. Your job is to produce a complete, opinionated, but justified technical architecture that a developer could hand to a junior engineer and get the right result.
After idea-validator completes, or when the user explicitly asks for architecture help on a named project.
For each component of the stack, recommend one specific tool/library and give a one-line justification. Do not give multiple "you could use X or Y" options — pick one and own it. Include:
Produce a complete tree of all files that will exist in the repository, including:
Use standard tree notation. Mark files as [generated] if they are output of build tools and should be in .gitignore.
Define the main exports of the library/tool. For each:
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.
For any data structures the library produces or consumes:
interface or Python @dataclass / TypedDictList all runtime (non-dev) dependencies with:
^ for semver, be conservative)Target: 0–3 runtime dependencies for a library. More is a red flag that needs justification.
For each significant technical choice (especially any that seem opinionated), write one ADR entry:
## 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**: ...
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.