Skip to content
Kesita Kesita Kesita docs

Kesita architecture

Kesita is a legal workspace backed by two data domains:

  • Product data contains organizations, projects, conversations, private files and generated work.
  • Legal data contains shared, versioned legal sources and their retrieval indexes.

The two domains remain separate. Product workloads can ask Legal Core for legal evidence through an authenticated API; they never query the legal database or corpus storage directly.

System map

Section titled “System map”
flowchart LR
  User[Lawyer] -->|HTTPS| App[Kesita app]
  App --> ProductAPI[Product API]
  ProductAPI --> ProductData[(Product PostgreSQL + private blobs)]
  ProductAPI --> Worker[Product worker + DBOS]
  Worker --> ProductData
  Worker -->|Workload JWT| LegalCore[Legal Core API]
  LegalCore --> LegalData[(Legal PostgreSQL + corpus originals)]
  Worker --> Providers[Model, OCR and embedding providers]
  CorpusWorker[Corpus worker] --> LegalData

Responsibilities

Section titled “Responsibilities”
BoundaryResponsibility
Kesita appBrowser UI, user session and same-origin gateway
Product APIAuthorization, commands, queries, uploads and saved progress
Product worker with DBOSDurable assignments, retries and long-running work backed by PostgreSQL
Legal Core APILegal search, immutable source versions and original delivery
Corpus workerImport, version and index approved legal material
PostgreSQL and blob storageAuthoritative state within their owning domain

Detailed service map

Section titled “Detailed service map”

This view expands the same boundaries into the deployable services and their principal dependencies. Arrows mean runtime calls or owned data access, not shared authorization.

flowchart LR
  subgraph Clients[Clients]
    Browser[Product browser]
    Operators[Admin browser]
    Partners[Future API clients]
    MCPHost[Future MCP hosts]
  end

  subgraph Web[Public application boundary]
    App[app<br/>Next.js UI and session gateway]
    PublicAPI[Future Public Legal API]
    MCP[Future MCP server]
  end

  subgraph Product[Product domain]
    ProductAPI[product-api<br/>authorization and commands]
    ProductDB[(product database)]
    ProductBlob[(product blobs)]
    Dispatcher[committed-command dispatcher]
    ProductWorker[product-worker<br/>DBOS workflow and capabilities]
    Parser[document-parser<br/>isolated extraction]
  end

  subgraph Legal[Shared legal domain]
    LegalCore[legal-api<br/>retrieval and source delivery]
    LegalDB[(legal database + pgvector)]
    CorpusBlob[(corpus originals)]
    CorpusWorker[corpus-worker<br/>import and indexing]
    Acquisition[approved source acquisition]
  end

  subgraph External[External providers]
    Clerk[Clerk identity]
    Models[Anthropic]
    Embeddings[Voyage]
    OCR[Document Intelligence]
    Email[Resend]
  end

  Browser -->|HTTPS| App
  Operators -->|HTTPS| App
  App -->|session verification| Clerk
  App -->|authenticated gateway| ProductAPI
  App -->|transactional email| Email
  Partners -. OAuth-protected HTTPS .-> PublicAPI
  MCPHost -. MCP over HTTPS .-> MCP
  MCP -. typed calls .-> PublicAPI

  ProductAPI -->|tenant-scoped SQL| ProductDB
  ProductAPI -->|private files and exports| ProductBlob
  ProductDB -->|committed command| Dispatcher
  Dispatcher -->|durable invocation| ProductWorker
  ProductWorker -->|checkpoints and results| ProductDB
  ProductWorker -->|originals and exports| ProductBlob
  ProductWorker -->|bounded bytes| Parser
  ProductWorker -->|generation| Models
  ProductWorker -->|private embeddings| Embeddings
  ProductWorker -->|OCR| OCR

  App -->|workload JWT| LegalCore
  ProductAPI -->|workload JWT| LegalCore
  ProductWorker -->|workload JWT| LegalCore
  PublicAPI -. policy-bound workload JWT .-> LegalCore
  LegalCore -->|read-only SQL| LegalDB
  LegalCore -->|checksum-verified read| CorpusBlob
  LegalCore -->|query embeddings| Embeddings
  Acquisition --> CorpusWorker
  CorpusWorker -->|versions and indexes| LegalDB
  CorpusWorker -->|create-only originals| CorpusBlob
  CorpusWorker -->|chunk embeddings| Embeddings

Solid paths exist in the current application architecture. Dashed Public API and MCP paths describe the future external boundary; they do not indicate deployed endpoints.

Durable work

Section titled “Durable work”

Interactive requests are short. Long-running work is admitted to PostgreSQL and executed durably through DBOS. The browser can leave and reconnect without owning the execution lifetime.

sequenceDiagram
  participant B as Browser
  participant A as Product API
  participant D as Product database
  participant W as Product worker + DBOS

  B->>A: Submit assignment
  A->>D: Commit assignment and command
  A-->>B: Accepted assignment ID
  D-->>W: Deliver committed command
  W->>D: Checkpoint and publish result
  B->>A: Reconnect to saved progress
  A-->>B: Events or current snapshot
Section titled “Legal evidence”

Legal sources are immutable versions with stable identifiers and provenance. Legal Core is the only runtime service allowed to read legal PostgreSQL and corpus originals. Private customer files remain in the product domain and never enter the shared corpus implicitly.

For future partner applications, MCP and the ComproCausa migration, see External API and MCP. For runtime placement and trust boundaries, see Deployment.