FENICE

AI-native, production-ready backend platform.

FENICE (Italian for "phoenix") is a backend starter platform built on the 2026 Golden Stack. It provides a complete foundation for production REST APIs with authentication, user management, AI agent discovery, and observability built in from the start.

---

Features

• Hono + Zod OpenAPI -- Type-safe routes with automatic OpenAPI 3.1 spec generation
• Zod v4 as Single Source of Truth -- One schema drives validation, TypeScript types, and API documentation
• Mongoose v9 + MongoDB -- Production-ready data layer with bcrypt password hashing
• JWT Authentication -- Access + refresh token flow with configurable expiry
• MCP Server Endpoint -- Model Context Protocol discovery for AI agent integration
• Scalar Interactive Docs -- Beautiful API documentation UI at /docs
• LLM-Readable Docs -- Markdown API reference optimized for AI consumption at /docs/llm
• FENICE 3D World (M1-M3.1) -- React + R3F city with real-time deltas, Tron visual language, AI builder UI
• OpenTelemetry -- Auto-instrumented distributed tracing
• Pino Structured Logging -- JSON logging with request correlation
• Adapter Pattern -- Vendor-independent abstractions for email (Resend), storage (GCS), messaging (FCM)
• Vitest + fast-check -- Modern testing with property-based testing support
• Docker Multi-Stage Build -- Optimized production images with health checks
• GitHub Actions CI -- Lint, typecheck, test, and build on every push
• Four-Script Pattern -- setup.sh, dev.sh, stop.sh, reset.sh for consistent workflows
• Husky + lint-staged -- Pre-commit quality enforcement

Quick Start

# Clone and enter
git clone https://github.com/formray/fenice.git
cd fenice

# Setup (installs deps, creates .env)
./setup.sh

# Start development (MongoDB via Docker + dev server)
./dev.sh

# Visit the API docs
open http://localhost:3000/docs

See QUICKSTART.md for a detailed walkthrough.

API Endpoints

| Method | Path | Auth | Description | | ------ | --------------------------------- | ----- | ----------------------------------- | | GET | /api/v1/health | No | Liveness check | | GET | /api/v1/health/detailed | No | Readiness check with dependencies | | POST | /api/v1/auth/signup | No | Register a new user | | POST | /api/v1/auth/login | No | Authenticate user | | POST | /api/v1/auth/refresh | No | Refresh access token | | POST | /api/v1/auth/logout | Yes | Revoke token | | POST | /api/v1/auth/verify-email | No | Verify email with token | | POST | /api/v1/auth/request-password-reset | No | Request password reset email | | POST | /api/v1/auth/reset-password | No | Reset password with token | | GET | /api/v1/users | Admin | List users (paginated, searchable) | | GET | /api/v1/users/me | Yes | Get current user profile | | GET | /api/v1/users/:id | Yes | Get user by ID | | PATCH | /api/v1/users/:id | Yes | Update user profile | | DELETE | /api/v1/users/:id | Admin | Delete user | | POST | /api/v1/upload/init | Yes | Initiate chunked upload | | POST | /api/v1/upload/:id/chunk | Yes | Upload a chunk | | POST | /api/v1/upload/:id/complete | Yes | Complete upload | | DELETE | /api/v1/upload/:id | Yes | Cancel upload | | POST | /api/v1/builder/generate | Admin | Start AI builder job | | GET | /api/v1/builder/jobs/:id | Yes | Get builder job status | | GET | /api/v1/builder/jobs | Admin | List all builder jobs | | POST | /api/v1/builder/jobs/:id/approve| Admin | Approve builder plan | | POST | /api/v1/builder/jobs/:id/reject | Admin | Reject builder plan | | GET | /api/v1/mcp | No | MCP discovery manifest | | WS | /api/v1/ws | Yes | Generic WebSocket messaging | | WS | /api/v1/world-ws | Yes | 3D world projection stream | | GET | /openapi | No | OpenAPI 3.1 JSON specification | | GET | /docs | No | Scalar interactive API docs | | GET | /docs/llm | No | LLM-readable Markdown docs |

Architecture

Client Request
  -> Middleware (requestId, requestLogger)
  -> Auth Middleware (JWT, on protected routes)
  -> OpenAPI Route (Zod validation)
  -> Service (business logic)
  -> Mongoose Model (MongoDB)
  -> JSON Response

Key design decisions:

• Hono over Express -- Modern, edge-ready framework with first-class OpenAPI support
• Zod as SSoT -- One schema for validation, types, and documentation eliminates drift
• Adapter pattern -- Swap email/storage/messaging providers without touching business logic
• MCP endpoint -- AI agents discover and use the API without human documentation
• OpenTelemetry -- Vendor-neutral observability from day one

See docs/ARCHITECTURE.md for detailed architecture decisions.

Project Structure

src/
  index.ts              # Hono app (routes, middleware, OpenAPI, Scalar)
  server.ts             # Entry point (MongoDB connect, seed admin, @hono/node-server)
  instrumentation.ts    # OpenTelemetry auto-instrumentation
  config/env.ts         # Zod-validated environment variables
  schemas/              # Zod schemas (SSoT for types + validation + OpenAPI)
  models/               # Mongoose models (User, BuilderJob)
  services/             # Business logic (auth, user, upload, projection, builder)
  routes/               # OpenAPI route definitions (8 routers)
  middleware/            # Auth, RBAC, rate-limiter, timeout, error handling, etc.
  ws/                   # WebSocket handlers + managers (generic + world)
  adapters/             # Email, storage, messaging abstractions
  utils/                # Errors, logger, crypto, pagination, query-builder, seed
client/
  src/                  # React + R3F 3D world client (M1-M3.1)
docs/3d-world/          # 3D world plans, ADRs, boards, and execution docs
tests/
  unit/                 # Unit tests (schemas, middleware, services, routes, ws)
  integration/          # Integration tests (health, auth, projection, world-ws)
  properties/           # fast-check property-based tests

Scripts

# Development
npm run dev              # tsx watch with OTel instrumentation
npm run dev:typecheck    # tsc --noEmit --watch

# Quality
npm run lint             # ESLint
npm run lint:fix         # ESLint with auto-fix
npm run format           # Prettier format all
npm run format:check     # Prettier check only
npm run typecheck        # TypeScript type checking
npm run validate         # lint + typecheck + test

# Testing
npm run test             # Vitest single run
npm run test:watch       # Vitest watch mode
npm run test:coverage    # Vitest with coverage

# Build
npm run build            # TypeScript compilation
npm run start            # Production server

# Shell scripts
./setup.sh               # First-time setup
./dev.sh                 # Start MongoDB + backend + 3D client
./stop.sh                # Stop Docker services
./reset.sh               # Full clean and reinstall

# Client (from client/)
npm run dev              # Vite dev server (3D client)
npm run lint             # Client ESLint
npm run typecheck        # Client TypeScript checks
npm run test             # Client Vitest
npm run build            # Client production build

Documentation

| File | Purpose | | ---------------------------------------------- | -------------------------------- | | CLAUDE.md | AI agent context file | | AGENTS.md | Machine-readable agent guide | | QUICKSTART.md | Zero-to-running guide | | CONTRIBUTING.md | Contribution guidelines | | CHANGELOG.md | Version history | | ROADMAP.md | Future plans | | docs/ARCHITECTURE.md | Architecture decisions | | docs/3d-world/00_START_HERE.md | 3D world execution entrypoint |

Contributing

See CONTRIBUTING.md for guidelines. In brief:

1. Fork the repo
2. Create a feature branch
3. Write tests (TDD preferred)
4. Ensure npm run validate passes
5. Submit a PR with Conventional Commit