API overview

The Cluster ERP server is one FastAPI application that create_app builds in src/cluster_erp/server/app.py. This page explains how its HTTP paths are formed, where the interactive API documentation is available, which content types the routes use, and what happens to one request between the socket and the service. It does not list endpoints; the API reference links one page per route group.

In short¶

• Every backend module mounts its routes under /api/v1/<module>, the value of ModuleBase.api_prefix (src/cluster_erp/core/module_base.py:37-38). The fleet and intranet modules write the same prefix as a literal (src/cluster_erp/modules/fleet/module.py:310, src/cluster_erp/modules/intranet/module.py:172).
• The module registry calls each module's register_routes while it loads the module (src/cluster_erp/core/module_registry.py:49-51).
• Shared routes outside the modules live in src/cluster_erp/server/routes/ and are included by create_app (src/cluster_erp/server/app.py:1432-1450).
• The interactive documentation pages exist only when the debug setting is on (src/cluster_erp/server/app.py:1296-1303).
• Request and response bodies are JSON, except file uploads (multipart form data) and file downloads.

Base paths¶

The table groups the paths that the server answers. The module and shared route counts are on the API reference page.

Module prefixes¶

Most modules create a module_router with prefix=self.api_prefix, include their sub-module routers into it, and include it into the application with an entitlement dependency. The inventory module is an example (src/cluster_erp/modules/inventory/module.py:52-62). Some modules skip the module_router and pass the prefix to app.include_router directly, for example analytics, app_store, logs, mail, privacy, and records (src/cluster_erp/modules/analytics/module.py:55, src/cluster_erp/modules/records/module.py:50-52).

A sub-module router adds its own prefix, for example /warehouses (src/cluster_erp/modules/inventory/warehouses/routes.py:33). Several routers have no prefix and write the resource segment into every route path instead: the crm routers, the calendars router, the parties routers, the sales order routers, the currency router, and the customer subscription router (src/cluster_erp/modules/crm/customers/routes.py:28, src/cluster_erp/modules/calendars/routes.py:44, src/cluster_erp/modules/parties/parties/routes.py:28, src/cluster_erp/modules/sales_orders/orders/routes.py:33, src/cluster_erp/server/routes/currencies.py:18, src/cluster_erp/modules/subscriptions/customer_subscriptions/routes.py:30-34). The module pages show the full path of every route, so a reader does not have to add the parts.

OpenAPI availability¶

create_app passes docs_url="/api/docs" and redoc_url="/api/redoc" only when settings.debug is true; otherwise both are None (src/cluster_erp/server/app.py:1296-1303). The debug setting defaults to False (src/cluster_erp/config/settings.py:176). The call passes no openapi_url argument, so the framework default applies; see the FastAPI reference. Two routes are excluded from the schema with include_in_schema=False: the closed-signup probe and /.well-known/security.txt (src/cluster_erp/server/app.py:1455, src/cluster_erp/server/app.py:1459). Each router passes tags, which group the operations in the generated schema, for example tags=["inventory-warehouses"] (src/cluster_erp/modules/inventory/warehouses/routes.py:33).

Content types¶

The path of one request¶

The diagram follows one authenticated request to a module route. It shows what the code does, not timing. The order in which the framework resolves the dependencies of one route is not stated in the project's code, so the three dependencies appear together.

sequenceDiagram
 participant Client
 participant Middleware
 participant Dependencies
 participant Handler
 participant Service
 participant Database
 Client->>Middleware: HTTP request
 Note over Middleware: _security_headers refuses an oversized body with 413
 Middleware->>Dependencies: call the route
 Note over Dependencies: get_db_session, require_app, require_permission
 Dependencies->>Database: open the tenant session, set the audit context
 Dependencies->>Handler: user and session, or 401, 403, 422
 Handler->>Service: validated schema
 Service->>Database: query and flush
 Service-->>Handler: result or AppError
 Handler-->>Middleware: response model
 Note over Middleware: commit before the first byte, activity log, security headers
 Middleware-->>Client: JSON response

The same steps in prose:

The middleware order and each layer are explained in Request pipeline and middleware.

Terms introduced¶

Related pages¶

• API reference
• Authentication and headers
• API conventions
• Errors
• Server startup and app factory
• Module lifecycle

Verified against commit 92f8051 on 2026-11-13.