Backend API Overview (`apps/api`)

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/src/index.ts
• apps/api/package.json
• apps/api/src/handlers/openapi.ts
• apps/api/src/middlewares/db.ts
• apps/api/src/lib/auth.ts
• README.md

The apps/api service is a modern, full-stack TypeScript backend built using the Hono web framework. It serves as the API layer for the monorepo, providing type-safe RPC endpoints via ORPC, authentication using better-auth, and automated API documentation with OpenAPI and Scalar. The API is designed with a contract-first approach, sharing types and schemas with the frontend through the @contract-based-monorepo/contract package.

This service is built to be fast and run on edge environments, leveraging Hono's performance. It integrates with a PostgreSQL database via Drizzle ORM (though the current implementation uses a fake in-memory database for demonstration) and exposes a clear, versioned API structure. The server starts on port 3001 by default.

Sources: README.md, apps/api/src/index.ts:18-24, apps/api/package.json

Architecture and Core Technologies

The API server is built on a foundation of Hono for routing and request handling. It employs a middleware-based architecture to manage concerns like authentication, database context, and request handling for different API styles (RPC vs. REST).

Sources: apps/api/src/index.ts, README.md

High-Level Architecture

The following diagram illustrates the flow of a request through the apps/api service, from the initial entry point in the Hono server to the various specialized handlers.

Key Dependencies

The functionality of the apps/api service is enabled by several key npm packages.

Package	Description
hono	The core web framework for building the API server.
@hono/node-server	Adapter to run the Hono application on Node.js.
@orpc/server	Provides the server implementation for the ORPC framework.
@orpc/openapi	Generates OpenAPI specifications from the ORPC contract.
better-auth	Handles user authentication, including email/password flows.
@scalar/hono-api-reference	Provides the Scalar UI for interactive API documentation.
@contract-based-monorepo/db	Workspace package for database schema and access (via Drizzle).
@contract-based-monorepo/contract	Workspace package defining the shared API contract.

Sources: apps/api/package.json:12-25

Server Entrypoint and Routing

The main entry point for the API server is apps/api/src/index.ts. This file initializes the Hono application, registers all middleware and route handlers, and starts the server.

Sources: apps/api/src/index.ts

Request Handling Flow

The server processes incoming requests through a series of middleware and handlers based on the request path.

// apps/api/src/index.ts:7-15
const app = new Hono<{ Variables: Bindings }>();

app.on(["POST", "GET"], "/api/auth/*", handleBetterAuth);
app.use("*", handleAuthContext);
app.get("/api/spec.json", handleOpenAPISpec);
app.get("/api/docs", handleScalarDocs);
app.use("/api/*", handleOpenAPIRequests);
app.use("/rpc/*", handleRPCRequests);

Registered Routes

The following table summarizes the routes configured in the Hono application.

Method	Path	Handler	Description
POST, GET	/api/auth/*	handleBetterAuth	Handles all authentication-related requests via better-auth.
*	*	handleAuthContext	A global middleware to process authentication context for all requests.
GET	/api/spec.json	handleOpenAPISpec	Serves the generated OpenAPI 3.0 specification in JSON format.
GET	/api/docs	handleScalarDocs	Serves the interactive Scalar API documentation UI.
*	/api/*	handleOpenAPIRequests	Handles RESTful requests that conform to the OpenAPI spec generated by ORPC.
*	/rpc/*	handleRPCRequests	Handles all type-safe RPC calls via the ORPC server.

Sources: apps/api/src/index.ts:9-15

Authentication

Authentication is managed by the better-auth library, configured in apps/api/src/lib/auth.ts. It is set up to use an email and password strategy and integrates with the database via a Drizzle adapter.

The configuration also includes the openAPI() plugin, which likely extends the OpenAPI specification with authentication-related endpoints.

// apps/api/src/lib/auth.ts:5-19
export const auth = betterAuth({
  emailAndPassword: {
    enabled: true,
  },
  plugins: [openAPI()],
  database: drizzleAdapter(db, {
    provider: "pg",
    schema: {
      user: schema.user,
      session: schema.session,
      account: schema.account,
      verification: schema.verification,
    },
  }),
});

Sources: apps/api/src/lib/auth.ts:5-19, apps/api/package.json:22

Database Middleware

The API uses a middleware to inject a database context into requests. The dbProviderMiddleware ensures that a db object is available in the Hono context for downstream handlers.

Currently, this middleware uses a createFakeDB function to provide an in-memory database for demonstration purposes. This fake database implements the DB interface and provides methods for interacting with a planets collection.

Sources: apps/api/src/middlewares/db.ts

DB Interface and Models

The structure of the database access layer and its models are defined in apps/api/src/middlewares/db.ts.

This diagram shows the DB interface and the Planet data model it manages.

API Documentation

The project automatically generates API documentation from the shared @contract-based-monorepo/contract package. This is handled by @orpc/openapi and served via two endpoints.

Sources: apps/api/src/handlers/openapi.ts

OpenAPI Specification Generation

A request to /api/spec.json triggers the generation of an OpenAPI specification. The OpenAPIGenerator uses the ORPC contract and a ZodToJsonSchemaConverter to produce the JSON output. The configuration specifies API metadata and a bearerAuth security scheme.

The following sequence diagram shows how the OpenAPI spec is generated.

Interactive Documentation UI

The /api/docs endpoint serves an interactive API documentation UI provided by Scalar. It is configured to point to the /api/spec.json endpoint to fetch the API definition and pre-fills a default bearer token for testing.

// apps/api/src/handlers/openapi.ts:32-41
export const handleScalarDocs = Scalar({
  url: "/api/spec.json",
  authentication: {
    preferredSecurityScheme: "bearerAuth",
    http: {
      bearer: {
        token: "default-token",
      },
    },
  },
});

Sources: apps/api/src/handlers/openapi.ts:32-41, apps/api/src/index.ts:12