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 Commits

License

MIT -- Copyright (c) 2023 Giuseppe Albrizio

---

Built with care by Formray.