audit-realworld — Full-Stack Gap Audit vs the RealWorld Reference

Degree of freedom: MIXED — Mode, parity, and routing [HIGH freedom]; Phase 4 contract-suite run [LOW freedom — run exactly] when a server or suite exists.

Read-only. Findings and a prioritized gap report only — no code changes. Remediation goes to the skill named per finding.

RealWorld ("Conduit") is an objectively testable full-stack benchmark: formal API spec, shared E2E suite, shared CSS theme, hosted API at api.realworld.show.

The RealWorld API spec and its E2E suite are the source of truth — not any single community implementation. Reference repos vary; the spec and the passing suite do not.

RealWorld is a demo spec, not a production bar. It omits rate limiting, observability, caching, CI/CD, secrets, and deployment. Report feature/ pattern parity, then delegate hardening to audit-security, plan-security-audit, plan-perf-audit, plan-rls-audit, and full-stack-ship-discipline.

How to reason — Observe → Interpret → Classify → Severity

1. Observe — quote the spec contract (or pattern) and the repo's file:line (or suite result)
2. Interpret — does this layer implement the contract, or only the UI/route?
3. Classify — Implemented / Partial / Missing / Diverges — or Bow-out if the repo is not a web CRUD+auth app
4. Severity — core Conduit / authz / list-contract gaps = High; production-omitted concerns are routed, not scored as RealWorld misses

Worked example

Observe: Conformance mode. GET /api/articles returns { articles } with no articlesCount and no limit/offset (app/api/articles/route.ts). Bruno list request fails the count assertion. Auth header is Token <jwt>. Interpret: the list contract is partial; clients cannot paginate. Auth scheme matches the spec. Classify: Partial (pagination / articlesCount); auth Implemented. Severity: High — feed is a core Conduit surface. Finding: Article list | no pagination / articlesCount | High | complete-everything

Phase 0 — Detect the stack and gate applicability [HIGH freedom]

Read the dependency manifest and source before comparing anything (reuse the audit-fe-api detection approach).

0a. Classify the stack

• Frontend: framework (React/Next/Vue/Nuxt/Svelte/Angular/Solid), router, state/data layer (TanStack Query, SWR, RTK, Pinia), HTTP client.
• Backend: framework (Express/Hono/Fastify/Nitro/NestJS/Django/Rails/Go/ Laravel/Spring), routing style, auth mechanism.
• Data layer: database + ORM/query builder (Prisma/Drizzle/TypeORM/Sequelize/ SQLAlchemy/ActiveRecord/Supabase), migration tool.
• Tests: unit runner, and any API/E2E harness (Bruno, Hurl, Postman/Newman, Playwright, Cypress).

0b. Applicability gate

Decide the mode — state which one and why, out loud:

If you bow out, say so plainly and recommend the fitting skills instead (audit-security, audit-performance, plan-perf-audit, audit-code-quality, audit-fe-api). Do not force a RealWorld comparison onto a repo it does not fit.

0c. Record the discovery

STACK: FE=<...> · BE=<...> · DB/ORM=<...> · tests=<...>
MODE: Conformance | Benchmark | Bow-out (reason)
RealWorld reference chosen: <stack impl> (spec-compliant? maintained?)

Phase 1 — Pull the reference (current) [HIGH freedom]

1a. Spec + test suite (source of truth)

• API spec and shared E2E suite live in the realworld-apps/realworld repo (specs/, Bruno .bru, Hurl .hurl) with a Postman collection for endpoint testing. The hosted API at api.realworld.show needs no keys.
• Fetch the current spec and note the exact endpoint/response/error contracts (summarized in Phase 2). Recognizing RealWorld is not knowing its current endpoint contracts — read the spec as published, not from memory.

1b. Closest-stack reference implementation

• Find the nearest implementation on codebase.show/projects/realworld, filter by the detected FE/BE stack. Prefer spec-compliant, recently maintained implementations (only a subset are verified spec-compliant at any time).
• Treat the reference as a pattern yardstick (folder structure, auth wiring, validation, error mapping) — not as gospel. When the reference and the spec disagree, the spec wins.

1c. Research current best practices

Follow the /research protocol for the detected stack (Context7 for library docs; Firecrawl for current patterns, dated to now). Anchor recommendations to the versions actually installed in the repo.

Phase 2 — Parity / pattern matrix [HIGH freedom]

Conformance mode — audit against the RealWorld contract

Enumerate the spec surface and mark each Implemented / Partial / Missing / Diverges, with file:line evidence:

Auth & users

• POST /api/users (register), POST /api/users/login
• GET /api/user, PUT /api/user (current user)
• Auth header scheme: Authorization: Token <jwt> (not Bearer)

Profiles

• GET /api/profiles/:username
• POST / DELETE /api/profiles/:username/follow

Articles

• GET /api/articles (filters: tag, author, favorited, limit, offset)
• GET /api/articles/feed (auth, followed authors)
• GET / POST / PUT / DELETE /api/articles/:slug
• POST / DELETE /api/articles/:slug/favorite

Comments & tags

• GET / POST /api/articles/:slug/comments, DELETE .../comments/:id
• GET /api/tags

Cross-cutting contracts

• Response envelopes: { user }, { profile }, { article }, { articles, articlesCount }, { comment(s) }, { tags }
• Validation errors: 422 with { "errors": { "body": [ ... ] } }
• Auth failures: 401; missing resources: 404
• Pagination: limit / offset, with articlesCount for lists
• Slug generation, favoritesCount, following/favorited booleans reflect the requesting user

Benchmark mode — map the patterns onto the repo's own domain

The repo isn't Conduit, so audit whether it exhibits the same production- relevant patterns RealWorld demonstrates, for its own resources:

Phase 3 — Full-stack coverage sweep [HIGH freedom]

Audit all three layers, not just whichever is easiest to read:

• Frontend: routes for each resource; auth flow (login/register/logout, token persistence, guarded routes); data layer (caching, error/loading/empty states); forms with validation and server-error surfacing.
• Backend: every spec/pattern endpoint present; auth middleware; input validation; consistent error mapping; pagination; correct status codes.
• Data layer: schema covers the entities and relations; migrations exist and are current; indexes on foreign keys and hot query paths; constraints (unique, not-null, FK) enforce integrity. Verify live via Supabase MCP when applicable.
• Tests: unit coverage on core logic, plus the RealWorld contract suite (or the repo's equivalent E2E harness).
• Build/config: app builds; env contract documented (names only).

Phase 4 — Live conformance test (optional but decisive) [LOW freedom — run exactly]

If a server is running or the E2E suite is present, run the objective proof:

• Run the RealWorld Bruno collection (bru run), the Hurl files (hurl --test), or the Postman collection (newman run) against the local API base URL. Report pass/fail per endpoint.
• If no server is available, state exactly how to run it (base URL, seed/demo credentials) rather than guessing conformance from code alone.

A passing contract suite is stronger evidence than any static reading. Save any run artifacts under .playwright-mcp/ if using playwright-cli.

Phase 5 — Production layering (the honest part) [HIGH freedom]

RealWorld parity is necessary breadth, not sufficient depth. Enumerate what RealWorld does not cover and route each to the right skill — do not imply parity means production-ready:

Phase 6 — Report (read-only) [HIGH freedom]

## RealWorld Full-Stack Audit — [repo] — [date]

**Mode:** Conformance | Benchmark
**Stack:** FE [..] · BE [..] · DB/ORM [..] · tests [..]
**Reference:** [closest-stack impl] (spec-compliant: yes/no)
**Live contract suite:** ran (N/M passed) | not run — [how to run]

### Implemented correctly
- [feature/pattern] — [file:line]

### Partial (works but incomplete or diverges)
| Feature/Pattern | Gap | file:line | Severity | Fix via |
|---|---|---|---|---|
| Article feed | No pagination / articlesCount | ... | High | complete-everything |

### Missing
| Feature/Pattern | file:line (where it should live) | Severity | Fix via |
|---|---|---|---|
| DELETE comment authz | ... | High | workflow-fix-and-ship |

### Diverges from spec (Conformance mode)
| Endpoint | Spec says | Repo does | file:line |
|---|---|---|---|
| Auth header | `Token <jwt>` | `Bearer <jwt>` | ... |

### Production gaps (NOT covered by RealWorld — separate hardening)
- Security → `audit-security` · Perf → `plan-perf-audit` · RLS → `plan-rls-audit` · ...

### Recommended order
1. [Critical conformance/parity gaps] → complete-everything / workflow-fix-and-ship
2. [Production hardening] → audit-security → plan-perf-audit → ...

Forbidden: claiming production-readiness from RealWorld parity alone; inventing conformance without running or precisely describing the contract test; silently skipping a layer (FE, BE, or DB).

Self-critique before reporting [LOW freedom — do not skip]

1. Evidenced — file:line or suite pass/fail, not "looks like Conduit"
2. Mode honest — Bow-out if no HTTP API + auth + owned resources; do not force a comparison
3. Suite honesty — ran N/M or stated exactly how to run; never invent conformance
4. All three layers — FE, BE, and data; skipping one is a failed audit
5. Not production-ready — RealWorld parity is never a security / perf / RLS pass
6. Nothing changed until approved

Related

• audit-fe-api — FE↔BE contract detail once endpoints are inventoried
• debug-fe-be-integration — reactive debugging of contract mismatches
• audit-security / plan-security-audit — the security depth RealWorld omits
• plan-rls-audit — Supabase access control
• plan-perf-audit / audit-performance — the performance depth RealWorld omits
• test-unit / test-playwright — write the coverage this audit finds missing
• complete-everything — close the parity + hardening gaps to done
• workflow-fix-and-ship — fix a single missing endpoint/feature and ship it
• full-stack-ship-discipline (rule) — migrations/functions must actually deploy