Living documentation · technical map

How LIA is built, layer by layer

The layers of the system from the screen to the database, what each building block does and with which technologies, where it lives in the repository, and the paths a request takes.

  • 59technical building blocks
  • 10layers
  • 7annotated journeys
  • 57infrastructure modules
  • 63business domains served

Version 4.6.0November 10, 2026kept current at every commit, from the repository's data

Overview

The layers of the system

From the screen to the database. Hover a building block to trace its links, click for its technologies, its files and its decisions.

relies onused by

Clients

What the person touches: the web app, its offline mode, the mobile shells and the messaging channels.

Edge

What stands between the Internet and the application: tunnel, content policy, rate limiting, sessions.

API and application core

The FastAPI API split into business domains, its SSE stream, its ordered startup and its configuration.

Agent orchestration

The LangGraph graph: routing, planning or ReAct loop, human approval, tools and response.

Models and costs

Access to each provider's models, reasoning, structured outputs, embeddings, and the accounting of every call.

Integrations

Clients for external services, open protocols, the sandbox and the voice channels.

Background jobs

What runs without a request: single-leader scheduler, proactive engine, durable jobs, self-diagnostics.

Data

Where state lives: PostgreSQL and pgvector, Redis, files, and the registers of what LIA did, read and decided.

Observability

Measure, see, alert, review: metrics, dashboards, alerts, logs, traces.

Delivery

How code becomes a service: images, continuous integration and its guards, qualified release, installer, demonstrator.

Journeys

Pick a scenario: its steps light up one by one on the map.

Layers

Click a layer to isolate it.

Journeys

The path of a request, a call, a release

Each step names the building block that acts and what it guarantees.

The journey of a chat message

From keyboard to screen, by way of the graph: one request, one stream, no token exposed.

  1. Web app
    The browser sends the message to the API on its own origin.
  2. Tunnel, CSP and rate limiting
    The tunnel routes it; the caller's rate limit is checked.
  3. Sessions and authentication
    The session cookie is validated server-side.
  4. FastAPI API by domain
    The chat route opens a stream and starts the graph.
  5. LangGraph graph
    The conversation state is reloaded from its checkpoint.
  6. Router
    The request is classified, the tools scored.
  7. Planner and executor
    A plan is written, validated, and executed in parallel.
  8. Tools and manifests
    Each tool goes through the authority gate and is recorded in the register.
  9. Connector clients
    The provider is called, with no database transaction open.
  10. Response synthesis
    The answer is synthesized from the results.
  11. SSE streaming
    It arrives word by word, with its cost, on the same stream.

A model call, end to end

Bounded before, translated for the provider, priced at the moment it is made, traced after.

  1. Versioned prompts
    The prompt is assembled: the stable part first, a single cache boundary.
  2. Accounting and ceilings
    Both ceilings — account and instance — are checked before any spending.
  3. Reasoning
    The reasoning intent is translated for this specific model.
  4. Model factory
    The provider's native client sends the request.
  5. Structured outputs
    An output cut off by the token limit becomes an explicit refusal.
  6. Accounting and ceilings
    Usage is read only once and priced at the time window of the call.
  7. Traceable registers
    The parameters actually sent go into the call's record.
  8. Metrics
    Tokens, latency and cost become metrics.

A proactive background job

A single leader, a jitter, a claim, a send settled from its result.

  1. Single-leader scheduler
    The leader triggers the sweep, offset by its jitter.
  2. Proactive engine
    Eligible accounts are selected under every rule.
  3. Connector clients
    The sources are read, each in a short transaction.
  4. Model factory
    The message is written within the spending ceilings.
  5. Traceable registers
    The send is claimed before it goes out.
  6. Push notifications
    The notification goes out to the browser or the phone.
  7. Traceable registers
    The effect is settled from the actual result of the send.

A delegated Live session

The delegated journey: the browser talks to the provider, and each request returns to the graph.

  1. Web app
    The person opens a Live session.
  2. Live transports
    The API issues a single-use credential and renders the voice's mandate.
  3. Live transports
    The browser opens the provider's transport (WebSocket or WebRTC).
  4. FastAPI API by domain
    A delegated request becomes an ordinary chat turn.
  5. LangGraph graph
    The graph runs it with its approvals and its registers.
  6. Live transports
    The answer, bounded and flattened, is handed back to the voice.
  7. Durable jobs
    At the end, a single closing step archives, tallies up and relays.

From commit to production

Every guard runs before the push; nothing is published without qualification.

  1. Continuous integration and guards
    The hook and CI run the same Task commands: lint, ratchets, tests.
  2. Continuous integration and guards
    On the tag, candidate images are built and tagged by digest.
  3. Release, deployment and installer
    A disposable install qualifies the candidate.
  4. Release, deployment and installer
    The release checks the evidence and publishes the version tags.
  5. Images and composition
    The pinned images are pulled onto the server.
  6. Release, deployment and installer
    The detached deployment writes its verdict to a file that is read back.
  7. Demonstrator
    The demonstrator is redeployed and checked.

See, alert, self-diagnose

Every signal has a reader; an alert has a runbook; LIA reads her own evidence.

  1. Metrics
    Processes publish their metrics, memory included.
  2. Logs
    Structured logs, free of personal data, go to Loki.
  3. Dashboards
    Grafana shows every subsystem.
  4. Alerts
    An alert goes out with its runbook.
  5. Self-diagnostics
    LIA gathers the evidence of the incident and diagnoses it.

Execute an application command

Durable identity and current preconditions; an opened continuation remains pending.

  1. Web app
    The client uses the operation catalogue offered to this account.
  2. Tools and manifests
    The declaration fixes the operation, schema, scope and required capabilities.
  3. Durable application commands
    Preparation binds before/after values, digest, actor, origin and expiry in an encrypted command.
  4. Approval and drafts
    The effect gate checks exact approval when the operation requires it.
  5. Durable application commands
    Execution rereads authority and capabilities; a token-fenced claim and the source service's compare-and-set protect their respective boundaries.
  6. Sessions and authentication
    A private continuation binds to the session and, where required, the addressed device; secrets stay outside the model.
  7. Durable application commands
    Committed, waiting, conflict, failure and cancellation remain distinct; a lost response is not automatically replayed.
  8. Web app
    An addressed hint invalidates affected resources; the client rereads their authenticated queries.