Reference implementation for the Phoenix Architecture. Work in progress. aicoding.leaflet.pub
6.1 kB · 202 lines
Markdown
at main

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 /health returns 200 with service name, uptime, module list
  • GET /metrics returns request counts
  • GET /modules lists all modules with risk tiers and exports
  • GET /unknown returns 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.