Skip to content

Hybrid development

Implemented

Hybrid CLI routing and checks exist. Use requires a provisioned development Legal API and provider credentials.

Code and tests

Hybrid development keeps product code and private product data local while routing legal requests through the deployed development Legal API.

Terminal window
./bin/kesita dev up app --hybrid
./bin/kesita dev up app --hybrid --mode container --detach
flowchart LR
    subgraph Local[Developer machine]
        App[Kesita app]
        Product[Product API and worker]
        Parser[Document parser]
        ProductData[(Product PostgreSQL<br/>and Azurite)]

        App --> Product
        Product --> ProductData
        Product --> Parser
    end

    subgraph Azure[Azure development]
        Legal[Legal API]
        LegalDB[(Legal PostgreSQL<br/>and pgvector)]
        Corpus[(Corpus originals)]

        Legal --> LegalDB
        Legal --> Corpus
        Legal --> Voyage[Voyage]
    end

    Product -->|HTTPS + workload JWT| Legal
    Product -->|real model calls| Anthropic[Anthropic]

The local stack does not start Legal Core, legal migrations, corpus workers, or legal fixtures. The deployed Legal API is the only path to the shared corpus and owns its database, Blob, and embedding credentials.

sequenceDiagram
    participant User
    participant App as Local Kesita app
    participant Product as Local product service
    participant Legal as Development Legal API
    participant Corpus as Legal data

    User->>App: Clerk session
    App->>Product: authenticated product request
    Product->>Product: mint short-lived workload JWT
    Product->>Legal: Legal API request + JWT
    Legal->>Legal: verify issuer, audience, key ID,<br/>expiry, service, scope and policy
    Legal->>Corpus: read using deployed identity
    Corpus-->>Legal: authorized result
    Legal-->>Product: contract response

Clerk authenticates the human. The workload JWT authenticates the Kesita service and carries organization, user, scope, and content policy. The remote API trusts only the public key configured for the development environment. The private key stays in the ignored local key file.

Local developers do not receive PostgreSQL, Blob, Voyage, or Azure service-principal credentials.

Generate the local workload key pair through the normal setup, then register its public half and key ID with the development Legal API. Copy the ignored template:

Terminal window
cp infra/env/hybrid.env.example infra/env/hybrid.env

Configure:

  • the HTTPS development Legal API URL;
  • private and public workload key file paths;
  • the matching workload key ID;
  • an Anthropic key and model available to the development account.

Then start and verify the loop:

Terminal window
./bin/kesita dev up app --hybrid
./bin/kesita dev doctor --hybrid

The doctor performs a real semantic search and original download through the Legal API, plus a small billable Anthropic request. It never prints corpus or provider bodies.

Hybrid mode is explicit and accepts only a remote HTTPS Legal API URL. Product database URLs must remain local. The CLI reads key files without placing their contents in the committed environment file.

Hermit remains the deterministic test gate and uses isolated simulations. Hybrid mode is a realistic integration check, not a replacement for automated tests.

./bin/kesita dev reset always rebuilds local simulated data and never modifies Azure resources.