Architecture and Runtime Foundations - Monorepo layout, workspace boundaries, and build graph
Overview
Dwilar/lita-api is organized as a pnpm monorepo with a Fastify + TypeScript backend at the center, surrounded by official SDK packages for Node.js, Java, and Python, plus a small set of operational and infrastructure stubs. The repository is shaped around the API as the primary runtime surface: the API app boots the HTTP server, the worker processes webhook deliveries, and the SDKs consume the API over HTTP rather than sharing process memory.
The workspace is intentionally split by runtime and packaging model. TypeScript backend apps compile to dist, the Node SDK publishes a package from dist, the Java SDK is built with Maven, and the Python SDK is built with setuptools. Supporting files such as turbo.json, pnpm-workspace.yaml, tsconfig.base.json, and workspace/README.md define the shared build and governance boundary, while frontend/next-env.d.ts exists as a generated Next.js typing shim and is not part of the backend runtime graph.
Repository Composition
The repository-level build and workspace graph is anchored by these root inputs:
| File |
Role in the repo |
pnpm-workspace.yaml |
Declares the pnpm workspace boundary used by the monorepo install and build flow. |
turbo.json |
Orchestrates workspace task execution in the build graph. |
tsconfig.base.json |
Shared TypeScript compiler baseline extended by backend apps. |
package.json |
Root package manifest referenced by the app Docker builds and workspace tooling. |
README.md |
Repository-level documentation entrypoint. |
workspace/README.md |
Durable workspace memory policy and long-lived operating notes. |
The app Dockerfiles copy package.json, pnpm-workspace.yaml, turbo.json, and tsconfig.base.json into the build context before installing dependencies, which makes those files part of every reproducible image build.
Runnable backend apps
| Workspace |
Manifest |
Runtime role |
Build output |
apps/api |
apps/api/package.json |
Fastify HTTP API server |
dist/index.js |
apps/worker |
apps/worker/package.json |
Webhook delivery worker |
dist/index.js |
Both apps use the same TypeScript build pattern:
dev: node --watch --loader ts-node/esm/transpile-only src/index.ts
build: tsc -p tsconfig.json
lint: eslint src --max-warnings=0
test: vitest
Both apps/api/tsconfig.json and apps/worker/tsconfig.json extend ../../tsconfig.base.json, which keeps compiler policy aligned across backend runtimes.
Official SDK packages
| Workspace |
Manifest |
Packaging model |
Primary purpose |
sdks/node |
sdks/node/package.json |
npm package with exports and dist publishing |
Official Node.js / TypeScript SDK |
sdks/java |
sdks/java/pom.xml |
Maven JAR |
Official Java SDK |
sdks/python |
sdks/python/pyproject.toml |
setuptools project |
Official Python SDK |
These SDKs are consumers of the API surface, not collaborators in the server build graph.
Support artifacts and service stubs
| Path |
Role |
packages/ |
Shared workspace package source copied into backend app image builds. The runtime imports show this folder houses internal @lita/* packages. |
infra/terraform/README.md |
Skeleton for infrastructure modules, including VPC, Postgres, Redis, and gateway. |
services/consent-service/Dockerfile |
Standalone Node 18 service stub exposing port 8081. |
services/scoring-orchestrator/Dockerfile |
Standalone Node 18 service stub exposing port 8082. |
The service stubs are deployment-shaped containers, but no application source is shown for them in the provided context.
Workspace memory files
workspace/README.md defines a persistent documentation memory area:
SOUL.md for mission and principles
MEMORIES.md for dated observations
DECISIONS.md for durable architectural and product decisions
TASKS.md for follow-up work
The same file states that every meaningful docs/code change must update at least one workspace file in the same commit, and that rule is enforced by pnpm workspace:check-memory through scripts/check-workspace-memory.mjs.
Frontend shim out of scope
frontend/next-env.d.ts is a generated Next.js type declaration file:
/// <reference types="next" />
/// <reference types="next/image-types/global" />
/// <reference path="./.next/types/routes.d.ts" />
It exists to satisfy Next.js typing, but it is not part of the backend runtime graph described here. The repository’s runtime center remains the API, worker, and SDK packages.
Architecture Overview
flowchart TD
subgraph RootWorkspace[Repository workspace foundation]
Pnpm[pnpm workspace yaml]
Turbo[turbo json]
TsBase[tsconfig base json]
Memory[workspace memory files]
end
subgraph BackendScope[Backend primary scope]
ApiApp[apps api]
WorkerApp[apps worker]
SharedPkgs[shared workspace packages]
end
subgraph ClientSDKs[Official SDK packages]
NodeSdk[sdks node]
JavaSdk[sdks java]
PythonSdk[sdks python]
end
subgraph SupportArtifacts[Support artifacts]
Terraform[infra terraform README]
ConsentStub[services consent service Dockerfile]
ScoringStub[services scoring orchestrator Dockerfile]
FrontendShim[frontend next env d ts]
end
Pnpm --> ApiApp
Pnpm --> WorkerApp
Pnpm --> NodeSdk
Pnpm --> JavaSdk
Pnpm --> PythonSdk
Turbo --> ApiApp
Turbo --> WorkerApp
TsBase --> ApiApp
TsBase --> WorkerApp
ApiApp --> SharedPkgs
WorkerApp --> SharedPkgs
NodeSdk --> ApiApp
JavaSdk --> ApiApp
PythonSdk --> ApiApp
Memory --> RootWorkspace
The graph is backend-first:
apps/api and apps/worker are the runnable server processes.
sdks/node, sdks/java, and sdks/python are client packages consuming the API.
packages/ provides shared workspace code used by the backend apps through workspace:* dependencies.
frontend/next-env.d.ts is present, but it is not part of the runtime graph above.
Build Graph and Runtime Entry Points
Workspace boundary heuristics visible in the manifests
The repository layout is not inferred from naming alone. The build graph is visible in the manifests and Dockerfiles:
workspace:* dependencies bind apps/api and apps/worker to internal workspace packages.
extends "../../tsconfig.base.json" shows that both backend apps inherit a shared TypeScript baseline.
pnpm install --frozen-lockfile in both app Dockerfiles proves that installs are reproducible from the root workspace lockfile.
pnpm -C apps/api build and pnpm -C apps/worker build show each app is compiled as its own unit.
sdks/node/package.json publishes dist via exports, while Java and Python use their own packaging systems.
frontend/next-env.d.ts is generated typing support, not a backend runtime package.
API runtime entry point
| File |
Runtime role |
apps/api/src/index.ts |
Delegates startup to buildServer(). |
apps/api/src/server.ts |
Builds the Fastify application, registers plugins and routes, and exposes health and OpenAPI endpoints. |
apps/api/src/index.ts is minimal:
const server = await buildServer();
apps/api/src/server.ts is the real composition root. It calls initOtel(), creates the Fastify instance, configures validation and serialization, registers middleware/plugins, mounts versioned and regional routes, and declares the base operational endpoints.
Worker runtime entry point
| File |
Runtime role |
apps/worker/src/index.ts |
Polls webhook deliveries in a long-lived loop. |
The worker imports prisma, signWebhook, and recordAuditEvent, which identifies it as a delivery processor rather than a request/response server. Its runtime loop polls pending or retryable deliveries, processes them in batches, logs failures, and sleeps between polling intervals.
Node SDK runtime entry point
| File |
Runtime role |
sdks/node/src/index.ts |
Public SDK facade that wires HttpClient into resource classes. |
sdks/node/src/webhooks.ts |
Webhook signature verification helper. |
The Node SDK is a thin client layer over the API. Its top-level Lita class composes resource objects around one HttpClient.
Java SDK runtime entry point
| File |
Runtime role |
sdks/java/src/main/java/com/joinlita/Lita.java |
Builder-based SDK facade. |
sdks/java/src/main/java/com/joinlita/HttpClient.java |
Transport and error translation layer. |
The Java SDK follows the same split as the Node SDK: one facade object, one transport, resource-specific classes, and model types for deserialization.
Python SDK runtime entry point
| File |
Runtime role |
sdks/python/lita/resources/*.py |
Resource classes for API calls. |
sdks/python/lita/webhooks.py |
Webhook verification helper. |
The Python SDK mirrors the HTTP client shape of the other SDKs, with resource objects wrapping a shared HttpClient.
Runtime Entry Points and Package Manifests
apps/api/package.json
| Field |
Value |
name |
@lita/api |
private |
true |
type |
module |
main |
dist/index.js |
Dependencies show the API runtime boundary:
- platform/runtime:
fastify, fastify-plugin, pino
- HTTP middleware and docs:
@fastify/cors, @fastify/helmet, @fastify/rate-limit, @fastify/swagger, @fastify/swagger-ui
- validation:
zod, fastify-type-provider-zod
- internal workspaces:
@lita/auth, @lita/core, @lita/db, @lita/compliance, @lita/observability, @lita/webhooks
- crypto/JWT support:
jose
apps/worker/package.json
| Field |
Value |
name |
@lita/worker |
private |
true |
type |
module |
main |
dist/index.js |
Dependencies show the worker’s narrow scope:
@lita/db
@lita/webhooks
@lita/compliance
The worker does not pull in the full HTTP stack because it is not an edge server.
sdks/node/package.json
| Field |
Value |
name |
@lita/node |
version |
1.2.0 |
main |
./dist/index.js |
types |
./dist/index.d.ts |
exports |
import, require, and types targets from dist |
files |
dist only |
This package is published as a client SDK artifact, not a private workspace app.
sdks/java/pom.xml
| Field |
Value |
groupId |
com.joinlita |
artifactId |
lita-java |
version |
1.2.0 |
packaging |
jar |
java.version |
11 |
Dependencies:
jackson-databind
jackson-datatype-jsr310
junit-jupiter for tests
sdks/python/pyproject.toml
| Field |
Value |
name |
lita-python |
version |
1.2.0 |
requires-python |
>=3.9 |
| build backend |
setuptools.backends.legacy:build |
Runtime dependency:
Development extras:
pytest
pytest-asyncio
mypy
ruff
respx
API Runtime Foundation
buildServer and apps/api/src/server.ts
buildServer() is the composition root for the API runtime. It does the following in order:
- Initializes telemetry with
initOtel().
- Creates a Fastify instance with:
logger: buildLogger()
bodyLimit: 1_048_576
- Applies Zod validator and serializer compilers.
- Registers:
cors
helmet
rateLimit
authPlugin
tenantPlugin
idempotencyPlugin
auditPlugin
- Registers route groups:
registerV1Routes(app)
usRoutes under /api/v1/us
jpRoutes under /api/v1/jp
- Declares operational endpoints:
/healthz
/readyz
/openapi.json
Public surface
| Method |
Description |
buildServer |
Builds and returns the configured Fastify app. |
Shared runtime dependencies
| Type |
Description |
buildLogger |
Creates the logger passed to Fastify. |
initOtel |
Initializes telemetry before the server is constructed. |
authPlugin |
Adds request authentication state and guards non-public routes. |
tenantPlugin |
Adds tenant-scoped request state. |
idempotencyPlugin |
Adds idempotency support to request handling. |
auditPlugin |
Adds request audit logging support. |
API boot flow
sequenceDiagram
participant Start as apps api src index ts
participant Server as buildServer
participant Telemetry as initOtel
participant Fastify as Fastify
participant Plugins as plugins and routes
participant Client as HTTP client
Start->>Server: buildServer
Server->>Telemetry: initOtel
Server->>Fastify: create app
Server->>Fastify: set validators and serializers
Server->>Plugins: register middleware and routes
Server-->>Start: app
Client->>Fastify: request to endpoint
Worker Runtime Foundation
apps/worker/src/index.ts
The worker is a polling process. The visible runtime shows these behaviors:
- imports shared persistence from
@lita/db
- imports webhook signing from
@lita/webhooks
- imports audit recording from
@lita/compliance
- defines
pollDeliveries()
- selects deliveries with:
status in pending or retrying
nextRetryAt is null or due
take: 10
- processes each delivery with
processDelivery(delivery.id)
- runs forever in
run()
- catches poll errors and logs
worker poll failed
Public surface
| Method |
Description |
pollDeliveries |
Fetches up to 10 pending or retryable deliveries and processes them. |
run |
Runs the polling loop continuously. |
Polling criteria
| Field |
Condition |
status |
pending or retrying |
nextRetryAt |
null or <= new Date() |
take |
10 |
Worker polling flow
sequenceDiagram
participant Loop as run
participant Poll as pollDeliveries
participant DB as prisma
participant Proc as processDelivery
participant Sleep as timer
Loop->>Poll: start iteration
Poll->>DB: query retryable deliveries
DB-->>Poll: delivery rows
loop each delivery
Poll->>Proc: processDelivery delivery id
end
Poll-->>Loop: complete
Loop->>Sleep: wait POLL_INTERVAL_MS
Sleep-->>Loop: next iteration
SDK Packages
Node SDK
The Node SDK is a client-facing package that wraps one transport instance and exposes resource objects.
sdks/node/src/index.ts
| Property |
Type |
Description |
consents |
ConsentsResource |
Consent-related API operations. |
features |
FeaturesResource |
Feature computation API operations. |
evidence |
EvidenceResource |
Evidence snapshot access. |
status |
StatusResource |
Async job status access. |
| Constructor dependency |
Type |
Description |
options |
LitaClientOptions |
API key, region, sandbox mode, base URL, and timeout. |
| Public method |
Description |
constructor |
Creates HttpClient and resource facades. |
sdks/node/src/resources/consents.ts
| Method |
Description |
create |
Creates a consent. |
get |
Fetches a consent by id. |
revoke |
Revokes a consent. |
getScore |
Retrieves the computed score. |
listTransactions |
Lists transactions for a consent. |
getKyc |
Retrieves KYC and AML results. |
sdks/node/src/resources/features.ts
| Method |
Description |
compute |
Triggers feature computation. |
sdks/node/src/resources/evidence.ts
| Method |
Description |
get |
Retrieves an evidence snapshot. |
sdks/node/src/resources/status.ts
| Method |
Description |
get |
Polls the status of an async job. |
sdks/node/src/webhooks.ts
| Method |
Description |
constructEvent |
Verifies X-Lita-Signature and parses a webhook event. |
Node SDK request flow
sequenceDiagram
participant App as SDK consumer
participant Lita as Lita
participant Resource as resource class
participant Http as HttpClient
participant Api as API server
App->>Lita: new Lita options
Lita->>Resource: create resource
App->>Resource: call method
Resource->>Http: get post or delete
Http->>Api: HTTP request
Api-->>Http: response
Http-->>Resource: parsed data
Resource-->>App: typed result
Java SDK
The Java SDK mirrors the Node SDK but uses a builder and typed model classes.
sdks/java/src/main/java/com/joinlita/Lita.java
| Property |
Type |
Description |
consents |
ConsentsResource |
Consent operations. |
features |
FeaturesResource |
Feature computation operations. |
evidence |
EvidenceResource |
Evidence retrieval operations. |
status |
StatusResource |
Job polling operations. |
| Constructor dependency |
Type |
Description |
builder |
Builder |
Supplies apiKey, region, optional baseUrl, timeout, and sandbox. |
| Public method |
Description |
consents |
Returns the consent resource. |
features |
Returns the features resource. |
evidence |
Returns the evidence resource. |
status |
Returns the status resource. |
builder |
Creates a new builder. |
sdks/java/src/main/java/com/joinlita/Lita.java builder
| Method |
Description |
apiKey |
Sets the API key. |
region |
Sets the target region. |
sandbox |
Enables sandbox routing. |
baseUrl |
Overrides the default base URL. |
timeout |
Sets the HTTP timeout. |
build |
Creates the Lita client. |
sdks/java/src/main/java/com/joinlita/HttpClient.java
| Property |
Type |
Description |
DEFAULT_BASE_URL |
String |
Default API base URL. |
apiKey |
String |
Bearer token used in requests. |
regionPrefix |
String |
Region or region plus sandbox segment. |
baseUrl |
String |
Normalized base URL. |
httpClient |
java.net.http.HttpClient |
Low-level HTTP transport. |
MAPPER |
ObjectMapper |
Shared JSON mapper. |
| Public method |
Description |
get |
Sends a GET request. |
post |
Sends a POST request. |
delete |
Sends a DELETE request. |
sdks/java/src/main/java/com/joinlita/resources/ConsentsResource.java
| Method |
Description |
create |
Creates a consent. |
get |
Fetches a consent. |
revoke |
Revokes a consent. |
getScore |
Retrieves a score. |
listTransactions |
Lists transactions without filters. |
listTransactions |
Lists transactions with query filters. |
getKyc |
Retrieves KYC data. |
sdks/java/src/main/java/com/joinlita/resources/FeaturesResource.java
| Method |
Description |
compute |
Triggers feature computation. |
sdks/java/src/main/java/com/joinlita/resources/EvidenceResource.java
| Method |
Description |
get |
Retrieves an evidence snapshot. |
sdks/java/src/main/java/com/joinlita/resources/StatusResource.java
| Method |
Description |
get |
Polls job status. |
sdks/java/src/main/java/com/joinlita/Webhooks.java
| Method |
Description |
constructEvent |
Verifies webhook signatures for byte arrays. |
constructEvent |
Verifies webhook signatures for UTF-8 strings. |
Java SDK model and parameter classes
sdks/java/src/main/java/com/joinlita/model/Consent.java
| Property |
Type |
consentId |
String |
status |
String |
applicantId |
String |
purpose |
String |
redirectUrl |
String |
createdAt |
String |
activatedAt |
String |
expiresAt |
String |
revokedAt |
String |
connections |
List<Connection> |
sdks/java/src/main/java/com/joinlita/model/Connection.java
| Property |
Type |
connectionId |
String |
provider |
String |
status |
String |
sdks/java/src/main/java/com/joinlita/model/ComputeFeaturesResponse.java
| Property |
Type |
jobId |
String |
status |
String |
consentId |
String |
estimatedCompletionMs |
int |
sdks/java/src/main/java/com/joinlita/model/EvidenceSnapshot.java
| Property |
Type |
evidenceRef |
String |
consentId |
String |
applicantId |
String |
snapshotVersion |
String |
createdAt |
String |
scoreInputs |
Map<String, Object> |
kycResult |
Map<String, Object> |
delinquencyBucket |
String |
sdks/java/src/main/java/com/joinlita/model/JobStatusResponse.java
| Property |
Type |
jobId |
String |
status |
String |
consentId |
String |
completedAt |
String |
error |
Map<String, String> |
sdks/java/src/main/java/com/joinlita/model/KycResult.java
| Property |
Type |
consentId |
String |
status |
String |
checks |
Map<String, Map<String, Object>> |
completedAt |
String |
sdks/java/src/main/java/com/joinlita/model/Transaction.java
| Property |
Type |
transactionId |
String |
date |
String |
amount |
double |
currency |
String |
description |
String |
category |
String |
type |
String |
sdks/java/src/main/java/com/joinlita/model/TransactionListResponse.java
| Property |
Type |
data |
List<Transaction> |
nextCursor |
String |
totalCount |
int |
sdks/java/src/main/java/com/joinlita/params/ConsentCreateParams.java
| Property |
Type |
applicantId |
String |
purpose |
String |
dataCategories |
List<String> |
expiresInDays |
int |
sdks/java/src/main/java/com/joinlita/params/TransactionListParams.java
| Property |
Type |
limit |
Integer |
cursor |
String |
fromDate |
String |
toDate |
String |
Python SDK
The Python SDK follows the same resource split as the Node and Java SDKs, but its concrete model classes are not shown in the provided context. The resource methods visible in sdks/python/lita/resources/*.py are:
| Resource |
Method |
Description |
ConsentsResource |
create |
Creates a consent. |
ConsentsResource |
get |
Fetches a consent. |
ConsentsResource |
revoke |
Revokes a consent. |
ConsentsResource |
get_score |
Retrieves a score. |
ConsentsResource |
list_transactions |
Lists transactions with optional filters. |
ConsentsResource |
get_kyc |
Retrieves KYC results. |
EvidenceResource |
get |
Retrieves an evidence snapshot. |
FeaturesResource |
compute |
Triggers feature computation. |
StatusResource |
get |
Polls job status. |
construct_event |
construct_event |
Verifies webhook signatures and parses the payload. |
Shared Infrastructure Services
Observability and telemetry
buildServer() initializes observability with initOtel() before constructing Fastify, and passes buildLogger() into the server logger configuration.
| Consumer |
Dependency |
apps/api/src/server.ts |
buildLogger, initOtel |
This establishes telemetry before route registration, so the API runtime is instrumented from startup.
Audit logging
apps/api/src/plugins/audit.ts decorates each request with logAuditEvent. The decorator gathers request-scoped data and forwards it to recordAuditEvent from @lita/compliance.
| Injected by |
Dependency |
auditPlugin |
recordAuditEvent |
| Captured fields |
Source |
tenantId |
this.tenantId |
actorType |
this.auth.actorType |
actorId |
this.auth.actorId |
action |
call input |
targetType |
call input |
targetId |
call input |
ip |
this.ip |
userAgent |
this.headers["user-agent"] |
metadata |
call input |
The visible callers are:
apps/api/src/routes/v1/tenants.ts
apps/api/src/routes/v1/credit-profiles.ts
apps/api/src/routes/v1/decisions.ts
apps/api/src/routes/v1/webhooks.ts
Webhooks delivery and verification
The repository uses @lita/webhooks in two directions:
- server-side delivery orchestration:
enqueueWebhookDelivery
listWebhookEndpoints
createWebhookEndpoint
- client-side verification:
constructEvent in Node, Java, and Python SDKs
- worker-side signing:
signWebhook imported in apps/worker/src/index.ts
Webhooks delivery flow
| Step |
Source |
Effect |
| Create endpoint |
webhooksRoutes.post("/endpoints") |
Persists { id, url, events }. |
| List endpoints |
webhooksRoutes.get("/endpoints") |
Returns the tenant’s endpoints. |
| Test delivery |
webhooksRoutes.post("/test") |
Enqueues a delivery for each endpoint. |
| Audit |
request.logAuditEvent |
Records webhook.endpoint.create or webhook.test. |
Webhook signature verification flow
| SDK |
Verification function |
| Node |
sdks/node/src/webhooks.ts constructEvent |
| Java |
sdks/java/src/main/java/com/joinlita/Webhooks.java constructEvent |
| Python |
sdks/python/lita/webhooks.py construct_event |
All three verify the X-Lita-Signature header with HMAC-SHA256 and reject mismatches before parsing the payload.
Webhook signature verification
sequenceDiagram
participant App as webhook consumer
participant Verify as constructEvent
participant Crypto as HMAC SHA256
participant Parse as JSON parser
App->>Verify: raw body, signature, secret
Verify->>Crypto: compute expected signature
Crypto-->>Verify: expected hash
Verify->>Verify: compare signatures
Verify->>Parse: parse payload
Parse-->>App: typed webhook event
HTTP Runtime Surface
Health check
Get Health
{
"title": "Get Health",
"description": "Returns the API liveness status.",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/healthz",
"headers": [],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"status\": \"ok\"\n}"
}
}
}
Readiness check
Get Readiness
{
"title": "Get Readiness",
"description": "Returns the API readiness status.",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/readyz",
"headers": [],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"status\": \"ready\"\n}"
}
}
}
OpenAPI document
Get OpenAPI Document
{
"title": "Get OpenAPI Document",
"description": "Returns the OpenAPI document served by the API runtime.",
"method": "GET",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/openapi.json",
"headers": [],
"queryParams": [],
"pathParams": [],
"bodyType": "none",
"requestBody": "",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"openapi\": \"3.0.3\",\n \"info\": {\n \"title\": \"Lita Platform API\",\n \"version\": \"1.2.0\"\n },\n \"paths\": []\n}"
}
}
}
Auth token introspection
Introspect Auth Token
{
"title": "Introspect Auth Token",
"description": "Returns an active flag plus the request auth context captured by the auth plugin.",
"method": "POST",
"baseUrl": "<ApiBaseUrl>",
"endpoint": "/v1/auth/token/introspect",
"headers": [
{
"key": "Authorization",
"value": "Bearer <PARTNER_API_KEY>",
"required": true
},
{
"key": "X-Request-Id",
"value": "<request-id>",
"required": true
},
{
"key": "Content-Type",
"value": "application/json",
"required": true
}
],
"queryParams": [],
"pathParams": [],
"bodyType": "json",
"requestBody": "{\n \"token\": \"tok_example_123\"\n}",
"formData": [],
"rawBody": "",
"responses": {
"200": {
"description": "Success",
"body": "{\n \"active\": true,\n \"tenantId\": \"tenant_12345\",\n \"scopes\": [\n \"admin:tenants\",\n \"admin:credit_profiles\"\n ]\n}"
}
}
}
Runtime and Package Graph Notes
API package boundary
[!NOTE]
openapi.json returns a static object with paths: {} even though buildServer() registers route groups and regional prefixes. The handler does not enumerate the mounted routes in the response body. [!NOTE] The handler computes active with Boolean(body.token), so any non-empty token string yields true. The authenticated request context in the response comes from the Authorization header processed by authPlugin, not from the posted token value.
apps/api is the widest backend package. It depends on:
- edge middleware:
@fastify/cors, @fastify/helmet, @fastify/rate-limit
- runtime framework:
fastify, fastify-plugin
- validation and contracts:
zod, fastify-type-provider-zod
- observability and logging:
@lita/observability, pino
- internal business and infrastructure packages:
@lita/auth, @lita/core, @lita/db, @lita/compliance, @lita/webhooks
This makes the API the primary composition layer for the backend.
Worker package boundary
apps/worker is narrower:
- shared persistence:
@lita/db
- webhook operations:
@lita/webhooks
- compliance audit recording:
@lita/compliance
It is isolated from the HTTP stack and only participates in asynchronous delivery processing.
SDK package boundaries
The SDKs are intentionally separated from the backend package graph:
sdks/node publishes a client API from dist
sdks/java packages a JAR with Jackson-based models
sdks/python packages a source distribution / wheel through setuptools
These packages consume the backend through HTTP and webhook verification, not through shared workspace runtime state.
Key Classes Reference
| Class |
Responsibility |
server.ts |
Builds the Fastify API runtime and mounts the route graph. |
auth.ts |
Enforces bearer authentication and decorates request auth state. |
audit.ts |
Adds audit logging to requests through request.logAuditEvent. |
index.ts |
Starts the API runtime and worker polling loop. |
Lita.ts |
Provides the Java SDK facade and builder-based client construction. |
HttpClient.java |
Sends Java SDK requests and normalizes API errors. |
ConsentsResource.java |
Exposes consent, score, transaction, and KYC operations in Java. |
FeaturesResource.java |
Exposes feature computation in Java. |
EvidenceResource.java |
Exposes evidence retrieval in Java. |
StatusResource.java |
Exposes async job polling in Java. |
Webhooks.java |
Verifies webhook signatures in Java. |
index.ts |
Exposes the Node SDK facade and resource wiring. |
webhooks.ts |
Verifies webhook signatures in the Node SDK. |
consents.py |
Exposes consent, score, transaction, and KYC operations in Python. |
evidence.py |
Exposes evidence retrieval in Python. |
features.py |
Exposes feature computation in Python. |
status.py |
Exposes async job polling in Python. |
webhooks.py |
Verifies webhook signatures in Python. |
us-api.ts |
Implements US-region consent and evidence helpers used by API routes. |
jp-api.ts |
Implements JP-region consent and evidence helpers used by API routes. |
Dependencies
Internal workspace dependencies
| Package |
Used by |
Role |
@lita/auth |
apps/api |
Bearer, JWT, and API key verification. |
@lita/core |
apps/api |
Tenant, decision, and credit profile operations. |
@lita/db |
apps/api, apps/worker |
Shared Prisma persistence. |
@lita/compliance |
apps/api, apps/worker |
Audit event recording. |
@lita/observability |
apps/api |
Logger and telemetry bootstrap. |
@lita/webhooks |
apps/api, apps/worker |
Webhook delivery and signing helpers. |
External package families
| Area |
Packages |
| HTTP server |
fastify, fastify-plugin |
| Security and transport |
@fastify/helmet, @fastify/cors, @fastify/rate-limit, jose |
| Validation |
zod, fastify-type-provider-zod |
| Logging |
pino |
| Node SDK transport |
standard fetch-style HTTP via the SDK client implementation |
| Java SDK transport |
java.net.http.HttpClient |
| Java JSON |
jackson-databind, jackson-datatype-jsr310 |
| Python HTTP |
httpx |
| Python packaging |
setuptools, wheel |
Testing Considerations
The visible manifests and entrypoints define a small number of concrete test surfaces:
- API server composition around
buildServer()
- worker polling loop and retry selection
- SDK resource request serialization and response parsing
- webhook signature verification helpers in Node, Java, and Python
- packaging boundaries:
- Node SDK
exports
- Java Maven artifact
- Python setuptools project
For this section, the most important runtime assertions are package-boundary assertions: apps/api and apps/worker must compile against the shared workspace packages, while each SDK must remain buildable and consumable as a standalone package.