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.shfor 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
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
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:
- Fork the repo
- Create a feature branch
- Write tests (TDD preferred)
- Ensure
npm run validatepasses - Submit a PR with Conventional Commits
License
MIT -- Copyright (c) 2023 Giuseppe Albrizio
Built with care by Formray.