chadfowler.com
Reference implementation for the Phoenix Architecture. Work in progress.
aicoding.leaflet.pub/
ai
coding
crazy
1/**
2 * Architecture: web-api
3 *
4 * An API-driven web application. Components communicate via REST endpoints.
5 * Each resource owns its data mutations. Components are independently
6 * testable via HTTP endpoint contracts.
7 *
8 * This architecture is language/runtime agnostic.
9 */
10
11import type { Architecture } from '../models/architecture.js';
12
13export const webApi: Architecture = {
14 name: 'web-api',
15 description: 'API-driven web application — REST endpoints, resource-oriented, independently testable',
16
17 communicationPattern: 'rest',
18 dataOwnership: 'per-component',
19 evaluationSurface: 'http-endpoints',
20
21 systemPrompt: `## Architecture: API-driven Web Application
22
23This system is an API-driven web application with the following architectural constraints:
24
25### Communication
26- Components communicate via REST HTTP endpoints
27- Each resource has its own set of endpoints (CRUD)
28- Standard HTTP status codes: 200 (ok), 201 (created), 204 (no content), 400 (bad request), 404 (not found)
29- All responses are JSON. Errors: { "error": "message" }
30
31### Data Ownership
32- Each resource module owns exclusive mutation authority over its database table(s)
33- Cross-resource queries use JOINs for read-only access
34- Foreign key relationships must be validated before mutation (check referenced row exists)
35- Cascade protection: cannot delete a parent resource that has dependent children
36
37### Component Grain
38- One module per resource (e.g., tasks, projects, categories)
39- Each module is independently deployable and testable
40- A web UI module serves HTML and calls the resource modules via fetch()
41
42### Evaluation Surface
43- Every module is testable via HTTP endpoint contracts
44- Create → verify response has ID and matches input
45- Read → verify response shape matches schema
46- Update → verify changes are persisted
47- Delete → verify resource is gone
48- Validation → verify 400 for invalid input
49- Not found → verify 404 for missing resources
50
51### Translating user requirements to implementation
52- "Users can create X" → POST endpoint with validation
53- "Users can view X" → GET endpoint with SELECT query (JOINs for related data)
54- "Users can edit X" → PATCH endpoint with UPDATE query
55- "Users can delete X" → DELETE endpoint with safety checks
56- "Users can filter by Y" → query parameters on GET endpoints
57- "Show X sorted by Y" → ORDER BY in query
58- "X must be visually highlighted" → UI concern, not API
59- "Expose a programmatic interface" → the REST API IS the programmatic interface
60`,
61
62 runtimeTargets: ['node-typescript'],
63};