Something went wrong. Try again.
Reference implementation for the Phoenix Architecture. Work in progress. aicoding.leaflet.pub
Something went wrong. Try again.
Phoenix VCS — Example Project #
A sample microservices platform with three specs: API Gateway, User Service, and Notification Service.
Quick Start #
# From the phoenix repo root, build and link the CLI (one-time)
cd /path/to/phoenix
npm run build
npm link
# Enter the example project
cd example
# 1. Initialize Phoenix
phoenix init
# 2. Bootstrap (ingest → canonicalize → plan → generate → scaffold)
phoenix bootstrap
# 3. Install generated project dependencies
npm install
# 4. Typecheck the generated code
npm run typecheck
# 5. Run all generated tests (52 tests)
npm test
# 6. Start a service
npm run start:api-gateway # http://localhost:3000
npm run start:user-service # http://localhost:3002
npm run start:notification-service # http://localhost:3001
Hit the Live Endpoints #
# Start the API Gateway
npm run start:api-gateway &
# Health check
curl localhost:3000/health | jq .
# Request metrics
curl localhost:3000/metrics | jq .
# List registered modules with risk tiers
curl localhost:3000/modules | jq .
# 404 for unknown routes
curl localhost:3000/nonexistent | jq .
Explore with Phoenix #
# Trust dashboard — the primary UX
phoenix status
# See what Phoenix extracted from specs
phoenix clauses # 26 clauses across 3 docs
phoenix canon # 87 canonical nodes (requirements, constraints, invariants)
# Inspect the IU plan
phoenix plan # 20 Implementation Units across 3 services
# Check generated files for unauthorized edits
phoenix drift
# Evaluate evidence against risk-tier policy
phoenix evaluate
# Provenance graph summary
phoenix graph
Make a Spec Change #
# Add a requirement
echo "- The gateway must support WebSocket upgrade requests" >> spec/api-gateway.md
# See the diff
phoenix diff spec/api-gateway.md
# Re-ingest → re-canonicalize → re-plan → regenerate
phoenix ingest
phoenix canonicalize
phoenix plan
phoenix regen
# Rebuild and test
npm run build
npm test
# Check status
phoenix status
Simulate Drift #
# Edit a generated file without going through Phoenix
echo "// unauthorized edit" >> src/generated/api-gateway/authentication.ts
# Drift detection catches it
phoenix drift # DRIFTED
phoenix status # Shows ERROR diagnostic
# Fix it by regenerating
phoenix regen
phoenix status # Clean again
Project Structure After Bootstrap #
example/
├── package.json # Generated — npm scripts for each service
├── tsconfig.json # Generated — strict TypeScript config
├── vitest.config.ts # Generated — test runner config
├── spec/ # Human-written specs
│ ├── api-gateway.md
│ ├── user-service.md
│ └── notification-service.md
├── src/generated/
│ ├── index.ts # Service registry
│ ├── api-gateway/
│ │ ├── index.ts # Barrel exports
│ │ ├── server.ts # HTTP server (:3000)
│ │ ├── authentication.ts # Module: validate(token)
│ │ ├── rate-limiting.ts # Module: rateLimit(input)
│ │ ├── request-routing.ts # Module: route(request)
│ │ ├── circuit-breaking.ts # Module: handle(request)
│ │ ├── logging-observability.ts
│ │ ├── request-transformation.ts
│ │ ├── security-constraints.ts
│ │ └── __tests__/
│ │ └── api-gateway.test.ts # 18 tests (modules + server)
│ ├── user-service/
│ │ ├── index.ts
│ │ ├── server.ts # HTTP server (:3002)
│ │ ├── account-management.ts # Module: create(input)
│ │ ├── search.ts # Module: search(user): User[]
│ │ ├── events.ts # Module: publish(event)
│ │ ├── profile-management.ts
│ │ ├── authentication-integration.ts
│ │ ├── data-constraints.ts
│ │ └── __tests__/
│ │ └── user-service.test.ts # 16 tests
│ └── notification-service/
│ ├── index.ts
│ ├── server.ts # HTTP server (:3001)
│ ├── email-delivery.ts
│ ├── push-notifications.ts
│ ├── delivery-guarantees.ts
│ ├── template-system.ts
│ ├── channel-support.ts
│ ├── in-app-messages.ts
│ ├── rate-limiting.ts
│ └── __tests__/
│ └── notification-service.test.ts # 18 tests
└── .phoenix/ # Phoenix state (not checked in)
├── state.json
├── graphs/
│ ├── spec.json
│ ├── canonical.json
│ ├── ius.json
│ └── warm-hashes.json
├── manifests/
│ └── generated_manifest.json
└── store/objects/
What Each Test Verifies #
Module tests (per module):
- Exports Phoenix traceability metadata (
_phoenix.name,_phoenix.risk_tier) - Has at least one exported function
Server tests (per service):
GET /healthreturns 200 with service name, uptime, module listGET /metricsreturns request countsGET /moduleslists all modules with risk tiers and exportsGET /unknownreturns 404
The Trace #
Every line of generated code traces back to a spec:
spec/api-gateway.md:9 "The gateway must validate JWT tokens..."
→ Clause 976a9f4b
→ CanonicalNode a890e171 (REQUIREMENT)
→ IU "Authentication" (high risk)
→ src/generated/api-gateway/authentication.ts
→ validate(jwtToken: JwtToken): boolean
Change that spec line → only authentication.ts is invalidated. Not the whole project.