# BAT-015 Design

## Architecture Decision

`jarca-ledger` is deployed as an independent Docker service that directly serves FastMCP `streamable-http` transport on port 8000. `genichin-agent` is no longer the process launcher for Jarca Ledger MCP. It may remain a client, but the Jarca Ledger service lifecycle belongs to Docker.

## Runtime topology

```text
finance-agent / Hermes client
    │
    │ Streamable HTTP MCP
    ▼
http://192.168.55.253:8000/mcp
    │
    ▼
jarca-ledger container
    ├─ jarca-ledger-mcp FastMCP server
    ├─ /data/ledger.sqlite3
    └─ Docker healthcheck on 127.0.0.1:8000
         │
         ▼
Synology host /volume1/docker/jarca-ledger/data
```

## Transport contract

- Default remains `stdio` when no env is set.
- `JARCA_MCP_TRANSPORT=streamable-http` runs Uvicorn/FastMCP network transport.
- `JARCA_MCP_HOST=0.0.0.0`, `JARCA_MCP_PORT=8000`, `JARCA_MCP_STREAMABLE_HTTP_PATH=/mcp` define the Docker service endpoint.
- Tool names and tool payload contracts remain unchanged.

## Data migration design

- Source: `jarca:/root/.local/share/jarca/ledger.sqlite3`
- Target: `jarca-ledger:/data/ledger.sqlite3`
- Snapshot method: SQLite `Connection.backup()` to avoid copying a live DB mid-write.
- Pre-replacement safety: back up the new empty `/data/ledger.sqlite3` under `/data/backups/pre_migration_empty_<timestamp>.sqlite3`.
- Verification: sha256, `PRAGMA integrity_check`, table counts, MCP `get_ledger_db_status`.

## Security and exposure boundary

- This batch exposes MCP only on the Synology host/internal network port mapping `8000:8000`.
- Internet exposure, reverse proxy, TLS, and auth policy are not included and must be handled as a separate approved change before external access.