microcodegen.py

PRD text → production FastAPI app → ZIP bytes. One Python file, zero dependencies.

Inspired by Andrej Karpathy's micrograd — this is the core Archiet algorithm in its simplest form.

python microcodegen.py your-prd.md --out ./myapp
cd myapp && pip install -r requirements.txt
alembic upgrade head
uvicorn main:app --reload

→ A working, bootable FastAPI app at http://localhost:8000/docs.

---

What it generates from your PRD

Given a plain-English Product Requirements Document, microcodegen.py outputs a complete FastAPI application:

• FastAPI with /docs interactive OpenAPI explorer — free, auto-generated by FastAPI
• SQLAlchemy 2.0 models — one per entity extracted from your PRD (DeclarativeBase)
• Pydantic v2 schemas — Base / Create / Update / Response classes per entity
• JWT auth — /api/auth/register, /api/auth/login, /api/auth/me with httpOnly cookies; never localStorage
• Full CRUD APIRouters — list, create, get, update, delete per entity; all Depends(get_current_user)
• Per-tenant data isolation — every row has a user_id FK; every query filters by it; no cross-user leaks
• Alembic migrations — alembic.ini + alembic/env.py pre-configured; run alembic upgrade head
• pytest test suite — TestClient with dependency_overrides, auto-skips if Postgres unreachable
• docker-compose.yml — Postgres 16 with healthcheck-gated app startup
• ARCHITECTURE.md — ArchiMate 3.2 element map typed from the genome IR
• openapi.yaml — machine-readable API contract; import into Postman or Swagger UI

Zero LLM calls. Zero API keys. Pure Python stdlib.

---

Run it

# Python 3.10+
git clone https://github.com/Anioko/microcodegen
cd microcodegen

# Generate from an example PRD
python microcodegen.py examples/task_manager.md --out ./my-task-app
cd my-task-app
pip install -r requirements.txt
alembic upgrade head
uvicorn main:app --reload
# → http://localhost:8000/docs

Or pipe the ZIP:

python microcodegen.py examples/task_manager.md > app.zip

Or install from PyPI:

pip install archiet-microcodegen
archiet-microcodegen examples/task_manager.md --out ./my-task-app

---

Write your own PRD

# Project Tracker

## Entities
- Project: name (string, required), description (text), status (string)
- Task: title (string, required), completed (boolean), due_date (datetime)
- Comment: body (text, required)

## User Stories
- As a developer, I want to manage projects so that I can track my work.
- As a developer, I want to add tasks to projects so that I can break work into steps.

Save as prd.md, run:

python microcodegen.py prd.md --out ./my-app

---

The four stages

PRD text  (your requirements document)
   │
   ▼  Stage 1: parse_prd(text) → manifest
   │  Pure regex extraction — entities, fields, user stories, integrations.
   │  No LLM. Misses subtle PRDs; that's acceptable for a spec reference.
   │
   ▼  Stage 2: manifest_to_genome(manifest) → genome
   │  Converts the manifest into a stack-neutral architectural genome dict.
   │  Adds ArchiMate 3.2 element typing (ApplicationComponent, DataObject,
   │  BusinessProcess, ApplicationService) for each extracted element.
   │
   ▼  Stage 3: render_genome(genome) → {path: content}
   │  string.Template substitution over embedded FastAPI templates.
   │  Outputs SQLAlchemy 2.0 models, Pydantic v2 schemas, APIRouters,
   │  Alembic env, pytest suite, ARCHITECTURE.md, openapi.yaml.
   │
   ▼  Stage 4: pack(files) → ZIP bytes
      stdlib zipfile.ZipFile. Download it, push it to GitHub, deploy it.

---

Why one file?

The same philosophy as micrograd and minGPT:

If you can't express the core algorithm in a single file, you're hiding behind layers.

microcodegen.py serves three purposes:

1. Onboarding — a new engineer understands what Archiet is in 10 minutes
2. Regression check — a bug that doesn't repro here is in the efficiency layers, not the algorithm
3. Spec — any algorithmic change (new genome key, new manifest field) updates this file first

---

What this file does NOT include

This is the minimum viable PRD→code pipeline. Production use cases need more:

Feature	Where it lives
LLM-powered PRD extraction (handles natural language)	archiet.com
9 backend stacks: NestJS, Django, Flask, Go (chi), Java Spring Boot, .NET, Laravel, Rails	archiet.com
React/Next.js frontend (shadcn/ui, auth pages, onboarding)	archiet.com
Expo mobile app (iOS + Android, push notifications)	archiet.com
Compliance artifact packs — SOC 2, HIPAA, GDPR, PCI-DSS control matrices	archiet.com
13-gate shippability audit (security scan, import coherence, boot test)	archiet.com
GitHub push + drift detection + architecture scoring	archiet.com
Quality score ≥ 80 gate (delivery blocked on broken output)	archiet.com

Free plan at archiet.com — 1 full app per month, no credit card.

---

Architecture deep dive

Stage 1 — parse_prd(text) → manifest

Pure regex extraction across four pattern classes:

• _ENTITY_PATTERN — finds entity section headers (## Entities, ## Data Models)
• _ENTITY_NAME_PATTERN — finds entity names as list items or sub-headers
• _FIELD_PATTERN — finds - fieldname: type (modifiers) declarations
• _USER_STORY_PATTERN — finds As a X, I want Y so that Z. sentences

The full Archiet pipeline replaces this with a chunked LLM extractor (overlap + dedup merge) that handles PRDs that don't follow a rigid format. The algorithm shape is identical — only the extraction quality changes.

Stage 2 — manifest_to_genome(manifest) → genome

Converts the manifest into a formal architectural genome — the stack-neutral intermediate representation that drives all downstream rendering.

The genome encodes:

• language — fastapi (this file's scope; the full system supports 12+ stacks)
• modules[] — one module per entity, with entities, user_stories, acceptance_criteria
• archimate_elements[] — every extracted element typed to ArchiMate 3.2 (ApplicationComponent for the app itself, DataObject per entity, BusinessProcess for workflow user stories, ApplicationService per integration)
• integrations[] — inferred from vendor mentions (Stripe, Auth0, SendGrid, etc.)

Stage 3 — render_genome(genome) → {path: content}

string.Template substitution across templates embedded directly in the file. Each template is a complete source file with $variable placeholders.

Templates emitted for every generated app:

• main.py — FastAPI entry point with include_router wiring (no create_all — Alembic owns the schema)
• app/database.py — SQLAlchemy 2.0 DeclarativeBase + get_db dependency
• app/auth.py — JWT via PyJWT + passlib/bcrypt, httpOnly cookie, get_current_user dependency
• app/models/user.py — User model
• alembic.ini + alembic/env.py — migration environment with model auto-discovery
• ARCHITECTURE.md — ArchiMate 3.2 element table
• openapi.yaml — full OpenAPI 3.1 spec

Per entity:

• app/models/<entity>.py — SQLAlchemy 2.0 model with user_id FK
• app/schemas/<entity>.py — Pydantic v2 Base / Create / Update / Response
• app/routers/<entity>.py — FastAPI APIRouter with full CRUD

Stage 4 — pack(files) → bytes

zipfile.ZipFile(DEFLATED). Maps {path: content} → ZIP bytes. The customer downloads this ZIP and runs it.

---

Examples

See examples/ for sample PRDs:

• task_manager.md — project/task management SaaS
• saas_billing.md — subscription billing with Stripe
• ecommerce.md — product catalog + orders

---

Contributing

The algorithm is intentionally simple. Before adding features, ask:

"Is this part of how a PRD becomes shippable code? Or is it tuning, fallback, or quality?"

If the former, open a PR. If the latter, it belongs in the full Archiet pipeline.

---

License

MIT. Use it, fork it, learn from it.

The production platform (12+ stacks, compliance packs, quality gates, GitHub push) is commercial: archiet.com