# nipalab/nipa architecture

> Architecture diagram of the GitHub repository nipalab/nipa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nipalab/nipa
- Repository: https://github.com/nipalab/nipa

## Overview

Nipa is a centralized version-control system for binary-heavy repositories. In the primary workflow, a developer uses the CLI to clone or edit a working copy, stage changes, and push commits; the client transfers chunked content to the server, which applies repository rules and persists metadata and chunks. Updates, branches, merges, diffs, locks, and merge requests support ongoing collaboration. GUI clients can use a local daemon, while browser users access repository and administration features through the web UI and HTTP API. The map follows the README and sampled startup, CLI, and daemon code; unsampled subsystem wiring is shown only where documented.

Main entry points: [`internal/client/usecase`](https://github.com/nipalab/nipa/tree/main/internal/client/usecase) (Client operations), [`internal/usecase`](https://github.com/nipalab/nipa/tree/main/internal/usecase) (Business usecases), [`cmd/nipad/main.go`](https://github.com/nipalab/nipa/blob/main/cmd/nipad/main.go) (Server entry), [`internal/client/cli`](https://github.com/nipalab/nipa/tree/main/internal/client/cli) (Nipa CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client workflow"]
  node_cli["Nipa CLI"]
  node_client_cases["Client operations"]
  node_client_rpc["Server transport"]
  node_working_copy[("Working copy")]
  node_chunking["Chunk transfer"]
  node_local_daemon["Local daemon"]
end

subgraph group_server["Server services"]
  node_server_entry["Server entry<br/>[main.go]"]
  node_grpc_api["gRPC services"]
  node_http_api["HTTP API"]
  node_business["Business usecases"]
  node_diff_engine["Diff engine"]
end

subgraph group_web["Web interface"]
  node_web_app["Nipa web app<br/>[App.tsx]"]
  node_web_api_client["Web API client<br/>[client.ts]"]
  node_web_server["Embedded web UI<br/>[webui.go]"]
end

subgraph group_persistence["Persistence"]
  node_chunk_store[("Chunk storage")]
  node_repositories[("Metadata repositories")]
end

node_developer(("Developer"))
node_gui_client(("GUI integrations"))
node_database[("SQL database")]
node_browser_user(("Browser user"))
node_keyring[("OS keyring")]

node_developer -->|"runs commands"| node_cli
node_cli -->|"dispatches operations"| node_client_cases
node_client_cases -->|"reads/writes state"| node_working_copy
node_client_cases -->|"requests server"| node_client_rpc
node_client_cases -->|"chunks content"| node_chunking
node_client_rpc -->|"RPC calls"| node_grpc_api
node_gui_client -->|"connects locally"| node_local_daemon
node_local_daemon -->|"runs operations"| node_client_cases
node_server_entry -->|"registers services"| node_grpc_api
node_server_entry -->|"routes HTTP"| node_http_api
node_grpc_api -->|"dispatches requests"| node_business
node_http_api -->|"handles API requests"| node_business
node_business -->|"reads/writes metadata"| node_repositories
node_business -->|"stores/retrieves chunks"| node_chunk_store
node_repositories -->|"queries"| node_database
node_business -.->|"compares trees"| node_diff_engine
node_browser_user -->|"uses browser"| node_web_app
node_web_app -->|"requests data"| node_web_api_client
node_web_api_client -->|"calls REST API"| node_http_api
node_server_entry -->|"serves UI"| node_web_server
node_cli -.->|"stores credentials"| node_keyring

click node_cli "https://github.com/nipalab/nipa/tree/main/internal/client/cli"
click node_client_cases "https://github.com/nipalab/nipa/tree/main/internal/client/usecase"
click node_client_rpc "https://github.com/nipalab/nipa/tree/main/internal/client/grpc"
click node_working_copy "https://github.com/nipalab/nipa/tree/main/internal/client/localrepo"
click node_chunking "https://github.com/nipalab/nipa/tree/main/internal/chunker"
click node_local_daemon "https://github.com/nipalab/nipa/tree/main/internal/client/daemon"
click node_server_entry "https://github.com/nipalab/nipa/blob/main/cmd/nipad/main.go"
click node_grpc_api "https://github.com/nipalab/nipa/tree/main/internal/grpc/server"
click node_http_api "https://github.com/nipalab/nipa/tree/main/internal/http/api"
click node_business "https://github.com/nipalab/nipa/tree/main/internal/usecase"
click node_diff_engine "https://github.com/nipalab/nipa/tree/main/internal/diff"
click node_chunk_store "https://github.com/nipalab/nipa/tree/main/internal/storage"
click node_repositories "https://github.com/nipalab/nipa/tree/main/internal/repository/sqlite"
click node_web_app "https://github.com/nipalab/nipa/blob/main/web/src/App.tsx"
click node_web_api_client "https://github.com/nipalab/nipa/blob/main/web/src/api/client.ts"
click node_web_server "https://github.com/nipalab/nipa/blob/main/web/server/webui.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_client_cases,node_client_rpc,node_working_copy,node_chunking,node_local_daemon,node_gui_client,node_browser_user toneBlue
class node_server_entry,node_grpc_api,node_http_api,node_business,node_diff_engine,node_database,node_keyring toneAmber
class node_web_app,node_web_api_client,node_web_server toneMint
class node_chunk_store,node_repositories toneRose
class node_developer toneIndigo
```

## Components

### Client workflow

- [Nipa CLI](https://github.com/nipalab/nipa/tree/main/internal/client/cli): `internal/client/cli`
- [Client operations](https://github.com/nipalab/nipa/tree/main/internal/client/usecase): `internal/client/usecase`
- [Server transport](https://github.com/nipalab/nipa/tree/main/internal/client/grpc): `internal/client/grpc`
- [Working copy](https://github.com/nipalab/nipa/tree/main/internal/client/localrepo): `internal/client/localrepo`
- [Chunk transfer](https://github.com/nipalab/nipa/tree/main/internal/chunker): `internal/chunker`
- [Local daemon](https://github.com/nipalab/nipa/tree/main/internal/client/daemon): `internal/client/daemon`

### Server services

- [Server entry](https://github.com/nipalab/nipa/blob/main/cmd/nipad/main.go): `cmd/nipad/main.go`
- [gRPC services](https://github.com/nipalab/nipa/tree/main/internal/grpc/server): `internal/grpc/server`
- [HTTP API](https://github.com/nipalab/nipa/tree/main/internal/http/api): `internal/http/api`
- [Business usecases](https://github.com/nipalab/nipa/tree/main/internal/usecase): `internal/usecase`
- [Diff engine](https://github.com/nipalab/nipa/tree/main/internal/diff): `internal/diff`

### Web interface

- [Nipa web app](https://github.com/nipalab/nipa/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Web API client](https://github.com/nipalab/nipa/blob/main/web/src/api/client.ts): `web/src/api/client.ts`
- [Embedded web UI](https://github.com/nipalab/nipa/blob/main/web/server/webui.go): `web/server/webui.go`

### Persistence

- [Chunk storage](https://github.com/nipalab/nipa/tree/main/internal/storage): `internal/storage`
- [Metadata repositories](https://github.com/nipalab/nipa/tree/main/internal/repository/sqlite): `internal/repository/sqlite`

### Other components

- **Developer**
- **GUI integrations**
- **SQL database**
- **Browser user**
- **OS keyring**

## Connections

- Developer → Nipa CLI: runs commands
- Nipa CLI → Client operations: dispatches operations
- Client operations → Working copy: reads/writes state
- Client operations → Server transport: requests server
- Client operations → Chunk transfer: chunks content
- Server transport → gRPC services: RPC calls
- GUI integrations → Local daemon: connects locally
- Local daemon → Client operations: runs operations
- Server entry → gRPC services: registers services
- Server entry → HTTP API: routes HTTP
- gRPC services → Business usecases: dispatches requests
- HTTP API → Business usecases: handles API requests
- Business usecases → Metadata repositories: reads/writes metadata
- Business usecases → Chunk storage: stores/retrieves chunks
- Metadata repositories → SQL database: queries
- Business usecases → Diff engine: compares trees
- Browser user → Nipa web app: uses browser
- Nipa web app → Web API client: requests data
- Web API client → HTTP API: calls REST API
- Server entry → Embedded web UI: serves UI
- Nipa CLI → OS keyring: stores credentials