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

Root workspace inputs

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:

  • httpx>=0.27.0

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:

  1. Initializes telemetry with initOtel().
  2. Creates a Fastify instance with:
    • logger: buildLogger()
    • bodyLimit: 1_048_576
  3. Applies Zod validator and serializer compilers.
  4. Registers:
    • cors
    • helmet
    • rateLimit
    • authPlugin
    • tenantPlugin
    • idempotencyPlugin
    • auditPlugin
  5. Registers route groups:
    • registerV1Routes(app)
    • usRoutes under /api/v1/us
    • jpRoutes under /api/v1/jp
  6. 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.