Architecture
How @axiljs/cloud is organized, which AxilJS packages it depends on, and how a request flows through the cloud middleware stack.
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.
| Area | Modules |
|---|---|
| Tenancy & Access | multi-tenancy, rate-limiter, correlation |
| Governance | audit, quota, feature-flags |
| Data & Secrets | cache, secrets |
| Deployment & Ops | deployment, 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/cloud ships as CommonJS with a single exports entry, so it loads with
both import and require().
Request Lifecycle
What each stage does:
correlationId()reuses or generatesreq_xxxandcorr_yyy, attaches them toreq.localsand echoes them in the response headers.multiTenancy()extracts the tenant ID from the header, subdomain, JWT or a custom resolver, validates its format and callsresolveTenant(id). It returns 401 if the tenant is missing, malformed, unknown, suspended or archived, and otherwise attaches it toreq.locals.tenant.tenantRateLimiter()looks up the tenant-specific rule, counts requests in a fixed (default) or sliding window, sets theX-RateLimit-*headers and returns 429 when the limit is exceeded.auditMiddleware()registers response'finish'and'close'handlers; on completion it emits an'audit.log'event.- 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 andsecrets.get()for credentials. - The response is sent to the client, and the audit event is emitted on
'finish'(or'close').
AxilJS Ecosystem Integration
| Package | Integration |
|---|---|
@axiljs/common | MiddlewareFn / RouteHandler types; tenancy throws UnauthorizedError (401) |
@axiljs/events | Audit (audit.log) and quota (quota.warning, quota.exceeded) events |
@axiljs/core | Middleware and handlers plug into Application and Router |
@axiljs/auth | The jwt tenancy strategy reads req.locals.user.tenantId set by authenticate() |
@axiljs/observability | The dashboard fetches the /metrics and /health endpoints you expose with it |
@axiljs/security | tenantRateLimiter() complements per-IP rateLimit() and helmet() |
@axiljs/config | Load encryptionKey and other settings from typed env config |
Full Integration Example
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?