API Server Setup

Relevant source files

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

• apps/api/src/app.ts
• apps/api/package.json
• apps/api/src/middleware/auth.ts
• apps/api/src/lib/jwt.ts
• turbo.json
• package.json

The Subito API server is a high-performance backend built using the Hono framework and running on Node.js. It serves as the central orchestration layer for the Subito platform, handling authentication, booking management, and partner assignments while interfacing with a PostgreSQL database via Drizzle ORM and managing background tasks with BullMQ.

The server architecture prioritizes security through a middleware-heavy pipeline, structured routing under versioned endpoints (v1), and strict environment configuration. It utilizes a monorepo structure managed by Turborepo, allowing for shared types and utilities across the API, dashboard, and database packages.
Sources: apps/api/package.json:23-38, apps/api/src/app.ts:5-15, turbo.json:5-20

Core Framework and Dependencies

The API server leverages the Hono framework for its lightweight and fast routing capabilities. It is designed to run in a Node.js environment using the @hono/node-server adapter.

Key Technology Stack

Component	Technology	Purpose
Routing Framework	Hono	Core web framework for handling HTTP requests.
Runtime Environment	Node.js	Execution environment for the JavaScript/TypeScript backend.
Validation	Zod	Schema-based validation for request payloads and environments.
Authentication	Jose	JWT (JSON Web Token) generation and verification.
Task Queue	BullMQ	Distributed job and message queue based on Redis.
Logging	Pino	Structured, low-overhead JSON logging.
Database	Drizzle ORM	TypeScript ORM for interacting with PostgreSQL.

Sources: apps/api/package.json:23-38, apps/api/src/app.ts:5-15

Server Initialization and Configuration

The server's entry point initializes the Hono application instance and applies a series of global middlewares. Configuration is strictly driven by environment variables, which are validated at runtime to ensure the application does not start with invalid settings.

Middleware Pipeline

The request processing pipeline follows a specific order to ensure safety and traceability:

1. Request ID: Generates a unique X-Request-Id for every incoming request.
2. Timing: Measures execution time for performance monitoring.
3. Logger: Captures request details (method, path, status, duration).
4. Secure Headers: Applies security-related HTTP headers.
5. CORS: Manages Cross-Origin Resource Sharing based on an environment-defined allowlist.
6. Client Tracing: Logs specific headers like X-Platform and X-App-Version for mobile/web client tracking.

Sources: apps/api/src/app.ts:41-86

The diagram shows the sequential execution of middlewares before a request reaches the core logic.
Sources: apps/api/src/app.ts:41-105

Authentication and Security

Authentication is implemented using JWTs (JSON Web Tokens) with a dual-token strategy (Access and Refresh tokens).

Token Management

The system uses the jose library to sign and verify tokens with an HS256 algorithm.

• Access Tokens: Short-lived (default 15m), containing user ID, role, and permissions.
• Refresh Tokens: Long-lived (default 30d), stored in the database and used to rotate access tokens.
• Permissions: Roles (customer, partner, admin) are mapped to specific scopes such as create:booking or update:partner_location.

Sources: apps/api/src/lib/jwt.ts:28-66

Auth Middleware Flow

The requireAuth middleware enforces token presence and validity. It also performs a "device mismatch" check by comparing the deviceId in the JWT against the X-Device-ID header.

Environment Variables

The server requires several critical environment variables to operate, particularly in production environments.

Variable	Requirement	Description
DATABASE_URL	Required	Connection string for PostgreSQL.
JWT_SECRET	Required (min 32 chars)	Secret key for signing HS256 JWTs.
CORS_ORIGINS	Required (Production)	Comma-separated list of allowed domains.
REDIS_URL	Required	Connection string for BullMQ and Caching.
FIREBASE_SERVICE_ACCOUNT	Required	Credentials for Firebase Admin SDK integration.

Sources: apps/api/src/app.ts:25-36, apps/api/src/lib/jwt.ts:9-14, turbo.json:6-21

Routing Structure

Routes are organized into a versioned hierarchy. The main application mounts a v1 router to handle all standard API operations.

• Public Routes: /health (system status) and / (API metadata).
• Auth Routes: Under /v1/auth, handling login, registration, and token rotation.
• Protected Routes: Enforced via requireAuth, requireAdmin, or requireRole middlewares.

Sources: apps/api/src/app.ts:93-105, apps/api/src/middleware/auth.ts:107-123

Build and Deployment

The project uses tsup for bundling the TypeScript code into ESM (ECMAScript Modules).

• Development: tsx watch src/index.ts provides a hot-reloading environment.
• Production Build: tsup src/index.ts --format esm compiles the code to the dist folder.
• Start: node dist/index.js executes the compiled production bundle.

Sources: apps/api/package.json:8-14

Summary

The API Server Setup for Subito establishes a secure, validated, and observable environment for cleaning service operations. By utilizing Hono's middleware architecture and a strict JWT-based authentication system, the server ensures that data integrity and user authorization are maintained across its versioned endpoints. The integration with Turborepo and structured environment management allows the server to scale and integrate seamlessly with other project components.