Skip to content

docs: add Aurelius-to-Nerva full-stack workflow guide#127

Merged
PAMulligan merged 1 commit into
mainfrom
23-document-aurelius-to-nerva-full-stack-workflow
Jun 13, 2026
Merged

docs: add Aurelius-to-Nerva full-stack workflow guide#127
PAMulligan merged 1 commit into
mainfrom
23-document-aurelius-to-nerva-full-stack-workflow

Conversation

@PAMulligan

Copy link
Copy Markdown
Contributor

Summary

Adds docs/schema-to-api/aurelius-pipeline.md, the dedicated walkthrough for the /build-from-aurelius pipeline. The pipeline was referenced across the docs (CLAUDE.md, architecture, README) but had no guide of its own, so one of Nerva's most distinctive features — generating a matching backend from a frontend build spec — was effectively undocumented.

What it covers

The guide carries a single storefront example end to end (the same domain the command's own mapping table uses):

  • How Aurelius generates build-spec.json — what the frontend records, with a concrete sample, and a callout distinguishing it from Nerva's own .claude/plans/build-spec.json (same filename, different file)
  • What Nerva extracts — the Phase 1 analysis that infers models, auth strategy, pagination, and constraints
  • How the OpenAPI spec is generated — the full generated OpenAPI 3.1 output, traced field-by-field back to the frontend
  • Confirming the mapping — the Phase 3 component → endpoint table
  • Handoff to /build-from-schema — into the standard 10-phase pipeline
  • The typed API client./scripts/generate-client.sh (openapi-typescript + optional openapi-fetch runtime), the files it emits, and how the frontend imports it for end-to-end type safety
  • Architecture diagram — an ASCII Aurelius ↔ Nerva data-flow diagram (matching the repo's diagram style; no Mermaid is used anywhere in the repo)
  • Frontend-only data (design tokens) handling and a troubleshooting table

Wiring

  • Linked from the main README.md — both the From Aurelius section and the Documentation table
  • Linked from docs/schema-to-api/README.md via a new Where the Spec Comes From section

Notes

  • Docs-only change; the affected CI job is the lychee link check. All internal link targets were verified to exist, the external Aurelius repo link returns 200, and inline-code backticks are balanced.

Closes #23

🤖 Generated with Claude Code

Add docs/schema-to-api/aurelius-pipeline.md, the dedicated walkthrough
for /build-from-aurelius that the docs referenced but never provided.

It carries one storefront example end to end:
- how Aurelius produces build-spec.json and what Nerva reads from it,
  distinguished from Nerva's own .claude/plans/build-spec.json
- the Phase 1 analysis that infers models, auth, and pagination
- the generated OpenAPI 3.1 spec
- the Phase 3 component-to-endpoint mapping and user confirmation
- the handoff to /build-from-schema
- the typed client from ./scripts/generate-client.sh and how the
  frontend imports it
- an ASCII Aurelius <-> Nerva data-flow diagram, plus frontend-only
  data handling and a troubleshooting table

Linked from the main README (From Aurelius section and the
Documentation table) and from docs/schema-to-api/README.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@PAMulligan PAMulligan linked an issue Jun 13, 2026 that may be closed by this pull request
8 tasks
@github-actions github-actions Bot added the area: docs Documentation label Jun 13, 2026
@PAMulligan PAMulligan merged commit 7e19777 into main Jun 13, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: docs Documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document Aurelius-to-Nerva full-stack workflow

1 participant