API Architecture
An overview of MuseMVP's API: why Hono, how it integrates with Next.js, and availability/observability entry points.
MuseMVP uses a Hono + Next.js Route Handler setup: all APIs go through /api/*, with Hono managing routes and middleware.
Overview
The request path keeps a single entrypoint: /api/* -> route.ts -> Hono app.ts -> feature router -> service/query.
Why Hono
The reasons are straightforward:
- Lightweight, with clear route and middleware organization
- TypeScript-friendly, making type-safe API clients easier to build
- Easy OpenAPI integration for interface collaboration
Compared to spreading logic across many Route Handlers, a centralized API layer is easier to maintain.
Availability
By default, API and Web are served together, so you do not need to maintain separate entrypoints.
If you later add mobile, plugins, or third-party clients, you can still reuse the same Hono routes.
Common route groups (examples):
/api(auth)/api/admin,/api/aichat,/api/upload/api/muse-billing,/api/upgrade,/api/newsletter/api/health/api/openapi,/api/docs
Layering convention:
- Route: input validation, auth, HTTP responses
- Service (
src/modules/<feature>/lib/*): business orchestration - Query (
src/backend/database/queries/*): database read/write
Observability
- Health check:
/api/health - OpenAPI:
/api/openapi - API docs (Scalar UI):
/api/docs
Practical Guideline
Keep middleware focused on entry responsibilities (logging, CORS, auth gate). Put complex business logic in the service layer to avoid API entry bloat.