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

src/app/api/[[...rest]]/route.ts

src/backend/api/app.ts

src/backend/api/routes/

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/assets, /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 (packages/db/src/queries/*): database read/write

Error Handling and Request Limits

src/backend/api/app.ts also registers two app-level guards:

app.onError catches uncaught errors and returns a consistent JSON error structure; thrown HTTPExceptions keep their own responses
hono/body-limit caps API request bodies at 1MB; uploads use presigned URLs to object storage

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.

MuseMVP uses a Hono + Next.js Route Handler setup: all APIs go through /api/*, with Hono managing routes and middleware.

Overview

src/app/api/[[...rest]]/route.ts

src/backend/api/app.ts

src/backend/api/routes/

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/assets, /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 (packages/db/src/queries/*): database read/write

Error Handling and Request Limits

src/backend/api/app.ts also registers two app-level guards:

app.onError catches uncaught errors and returns a consistent JSON error structure; thrown HTTPExceptions keep their own responses
hono/body-limit caps API request bodies at 1MB; uploads use presigned URLs to object storage

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.

Overview

Why Hono

Availability

Error Handling and Request Limits

Observability

On this page

API Architecture

Overview

Why Hono

Availability

Error Handling and Request Limits

Observability

On this page