Cloud

Architecture

How @axiljs/cloud is organized, which AxilJS packages it depends on, and how a request flows through the cloud middleware stack.

3 min readUpdated DocumentationEdit this page
On this page5

Platform Overview

@axiljs/cloud is a set of composable capability modules that share a single type system (types.ts) and the AxilJS global event bus.

AxilJS Cloud Platform
Tenancy & AccessGovernanceData & SecretsDeployment & Ops
AreaModules
Tenancy & Accessmulti-tenancy, rate-limiter, correlation
Governanceaudit, quota, feature-flags
Data & Secretscache, secrets
Deployment & Opsdeployment, dashboard, health-aggregator

Module Dependency Graph

The package has two peer dependencies and no third-party runtime dependencies; everything else uses node: built-ins (crypto, http, https, fs).

@axiljs/common@axiljs/events
@axiljs/cloud
@axiljs/common provides errors and types; @axiljs/events provides the global event bus.

@axiljs/cloud ships as CommonJS with a single exports entry, so it loads with both import and require().

Request Lifecycle

Incoming HTTP request
correlationId()
multiTenancy()
tenantRateLimiter()
auditMiddleware()
Your business logic
Response sent to client
The audit event is emitted when the response finishes (or the connection closes).

What each stage does:

  1. correlationId() reuses or generates req_xxx and corr_yyy, attaches them to req.locals and echoes them in the response headers.
  2. multiTenancy() extracts the tenant ID from the header, subdomain, JWT or a custom resolver, validates its format and calls resolveTenant(id). It returns 401 if the tenant is missing, malformed, unknown, suspended or archived, and otherwise attaches it to req.locals.tenant.
  3. tenantRateLimiter() looks up the tenant-specific rule, counts requests in a fixed (default) or sliding window, sets the X-RateLimit-* headers and returns 429 when the limit is exceeded.
  4. auditMiddleware() registers response 'finish' and 'close' handlers; on completion it emits an 'audit.log' event.
  5. Your business logic can use getTenant(req) for tenant context, featureFlags.isEnabled() for gradual rollouts, quotas.increment() to track resource usage, cache.get()/set() for performance and secrets.get() for credentials.
  6. The response is sent to the client, and the audit event is emitted on 'finish' (or 'close').

AxilJS Ecosystem Integration

PackageIntegration
@axiljs/commonMiddlewareFn / RouteHandler types; tenancy throws UnauthorizedError (401)
@axiljs/eventsAudit (audit.log) and quota (quota.warning, quota.exceeded) events
@axiljs/coreMiddleware and handlers plug into Application and Router
@axiljs/authThe jwt tenancy strategy reads req.locals.user.tenantId set by authenticate()
@axiljs/observabilityThe dashboard fetches the /metrics and /health endpoints you expose with it
@axiljs/securitytenantRateLimiter() complements per-IP rateLimit() and helmet()
@axiljs/configLoad encryptionKey and other settings from typed env config

Full Integration Example

TypeScript
TS
1import { Application, cors } from '@axiljs/core'
2import { loadEnv } from '@axiljs/config'
3import { helmet } from '@axiljs/security'
4import { JWT, authenticate } from '@axiljs/auth'
5import { MetricsRegistry, HealthChecker, observabilityMiddleware, metricsHandler } from '@axiljs/observability'
6import {
7  correlationId,
8  multiTenancy,
9  tenantRateLimiter,
10  auditMiddleware,
11  createDashboard,
12} from '@axiljs/cloud'
13
14loadEnv()
15const jwt = new JWT(process.env.JWT_SECRET!)
16const metrics = new MetricsRegistry()
17const health = new HealthChecker()
18
19const app = new Application()
20
21app.use(helmet())
22app.use(cors({ origin: '*' }))
23app.use(observabilityMiddleware({ metrics }))
24app.use(correlationId())
25app.use(authenticate(jwt, { required: false }))
26app.use(multiTenancy({ strategy: 'jwt', resolveTenant: (id) => db.tenants.findById(id) }))
27app.use(tenantRateLimiter({ defaultRule: { max: 100, windowMs: 60_000 } }))
28app.use(auditMiddleware())
29
30app.get('/dashboard', createDashboard({ title: 'Admin' }))
31app.get('/health', health.handler())
32app.get('/metrics', metricsHandler(metrics))
33
34app.listen(3000)

Note

Global middleware runs for every route, so /dashboard, /health, and /metrics above also require a tenant. In practice, apply multiTenancy() and tenantRateLimiter() to a mounted API Router and leave operational routes outside it.

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY