# ramin1886/dabiran architecture

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

- Interactive diagram: https://gitdiagram.com/ramin1886/dabiran
- Repository: https://github.com/ramin1886/dabiran

## Overview

1. **What this repo is**
   - This is a self-hosted “Git visualization platform” monorepo: a browser-based collaborative canvas on top of Git histories, backed by a Go API, a Rust dependency-analysis worker, PostgreSQL, and deployment assets for containers/Kubernetes/Terraform.

2. **Primary runtime split**
   - **Frontend:** `apps/frontend/` is a React + TypeScript + Vite app using PixiJS/WebGL for the canvas.
   - **Backend:** `apps/backend/` is the main Go service exposing REST APIs and a WebSocket collaboration layer.
   - **Worker:** `apps/worker/` is a Rust service that performs repository-manifest/dependency processing.
   - **Shared packages:** `packages/*` hold common types, utilities, and a WebAssembly math engine used by the frontend.

3. **Frontend architecture**
   - The UI is centered around a canvas-driven graph experience, not a traditional form-based web app.
   - `Canvas.tsx`, `NodeEngine.tsx`, and `CommitPanel.tsx` indicate a split between rendering, graph layout/interaction, and commit-detail side UI.
   - State is split into local app state (`useStore.ts`) and collaborative CRDT state (`useCRDT.ts`), with a view-state layer for zoom/pan and viewport behavior.
   - `src/api/client.ts` is the frontend boundary for backend data fetches.

4. **Real-time collaboration path**
   - Collaboration is WebSocket-based on the backend and Yjs/CRDT-based on the frontend.
   - The repo includes backend `ws/` components (`hub`, `client`, `store`) and frontend mocks for `y-websocket`, which suggests live cursors, shared annotations, and synchronized document state.
   - The collaboration subsystem is separate from the core repository visualization data model, so diagrams should show it as a side channel alongside normal REST fetching.

5. **Backend API boundaries**
   - `apps/backend/src/api/` contains the HTTP surface: router, middleware, search, repositories, views, dependency links, and webhooks.
   - This suggests a REST-style API for repository management, query/filtering, view state, and inbound webhook/event ingestion.
   - The API layer is the integration point between frontend requests and backend services like Git topology, persistence, auth, and websocket coordination.

6. **Git processing and graph generation**
   - `gitengine/` is the backend’s core domain engine for reading and organizing Git history.
   - The README’s topology model maps to this subsystem: chronological layout, branch lanes, split/merge connectors, and multi-repo node identities.
   - `search/` likely operates on the graph/model produced by the Git engine, enabling client-side or server-side filtering by commit metadata while preserving structural nodes for context.

7. **Authentication and identity**
   - `auth/` contains GitHub OAuth, JWT handling, and related auth logic.
   - The system uses GitHub as an upstream identity provider, but sessions are issued as JWTs with RBAC claims.
   - `middleware.go` is the enforcement layer for request authentication/authorization, so access control is a backend boundary, not a frontend-only concern.

8. **Data persistence and security**
   - `db/` connects the backend to PostgreSQL, which stores users, teams, repositories, and annotations per the README.
   - `crypto/` and `secrets/` indicate encrypted-at-rest secret handling, with AES-256-GCM called out in the README and a dedicated master-key path.
   - This makes the architecture security-sensitive: credentials and sensitive configuration are not stored in plaintext and are isolated from the app logic.

9. **Repository mirroring and external integration**
   - The platform is built around local bare Git clones rather than direct remote browsing.
   - `webhooks.go` suggests external Git events can trigger updates, which fits the model of mirrored repositories feeding the internal graph/indexing pipeline.
   - Any diagram should show external Git providers and GitHub OAuth as outside systems that feed authentication and repository update flows into the backend.

10. **Worker subsystem**
   - `apps/worker/` is a separate Rust service, described as `git-dep-worker`, for parsing manifests and generating cross-repository dependency links.
   - This is a batch/async processing boundary distinct from the interactive canvas path.
   - The output likely enriches repository metadata in the backend/database so the frontend can render or query dependency relationships between repos.

11. **Shared code and WebAssembly math**
   - `packages/shared-types/` provides cross-app TypeScript contracts that mirror the backend wire format, reducing drift between Go and TS.
   - `packages/utils/` holds shared pure helpers such as hash/viewport utilities.
   - `packages/wasm-math/` is a Rust-to-WebAssembly module for performance-sensitive canvas math like viewport culling and Bezier flattening, which sits between the frontend and rendering engine.

12. **Infrastructure and delivery**
   - `infra/docker-compose.yml` supports local containerized development, while `infra/kubernetes/` contains base and production overlay manifests for deployment.
   - `infra/terraform/` scaffolds cloud infrastructure, and `cicd/` holds build/test/deploy definitions.
   - The repo is therefore designed as a cloud-native, self-hosted system with separate build/deploy concerns from application code.

13. **How to draw the main data flows**
   - A useful diagram should show: Git providers and GitHub OAuth on the outside; backend as the central hub; PostgreSQL as durable state; bare Git storage/topology generation inside backend; WebSocket/Yjs collaboration as a realtime side channel; frontend as the WebGL client consuming REST plus collaboration streams; and the Rust worker as an async enrichment pipeline feeding dependency links back into persistence/API data.

Main entry points: [`apps/backend/src/api/router.go`](https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/api/router.go) (HTTP API), [`apps/frontend/src/App.tsx`](https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/App.tsx) (Canvas UI), [`infra/kubernetes/base/kustomization.yaml`](https://github.com/ramin1886/dabiran/blob/main/infra/kubernetes/base/kustomization.yaml) (Kubernetes), [`apps/backend/src/db/db.go`](https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/db/db.go) (Postgres)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["Canvas UI<br/>react client<br/>[App.tsx]"]
  node_frontend_canvas["Canvas<br/>PixiJS view<br/>[Canvas.tsx]"]
  node_frontend_node_engine["Node engine<br/>layout/interaction<br/>[NodeEngine.tsx]"]
  node_frontend_commit_panel["Commit panel<br/>detail sidebar<br/>[CommitPanel.tsx]"]
  node_frontend_api["API client<br/>REST client<br/>[client.ts]"]
  node_frontend_store["App state<br/>local state<br/>[useStore.ts]"]
  node_frontend_crdt["CRDT state<br/>collab state<br/>[useCRDT.ts]"]
  node_frontend_view["View state<br/>viewport state<br/>[viewState.ts]"]
  node_frontend_math["Math engine<br/>WASM helper<br/>[engine.ts]"]
end

subgraph group_backend["Backend"]
  node_backend_api["HTTP API<br/>Go router<br/>[router.go]"]
  node_backend_middleware["Middleware<br/>auth boundary<br/>[middleware.go]"]
  node_backend_gitengine["Git engine<br/>domain engine<br/>[engine.go]"]
  node_backend_search["Search<br/>query service<br/>[search.go]"]
  node_backend_ws["WebSocket hub<br/>realtime server<br/>[hub.go]"]
  node_backend_auth["Auth<br/>identity<br/>[oauth.go]"]
  node_backend_db[("Postgres<br/>persistence<br/>[db.go]")]
  node_backend_crypto["Crypto<br/>encryption<br/>[crypto.go]"]
  node_backend_secrets["Secrets<br/>secret mgmt<br/>[secrets.go]"]
  node_backend_models["Models<br/>data model<br/>[models.go]"]
end

subgraph group_worker["Worker"]
  node_worker_app["Dep worker<br/>Rust service<br/>[main.rs]"]
end

subgraph group_shared["Shared"]
  node_shared_types["Shared types<br/>contracts<br/>[index.ts]"]
  node_shared_utils["Utils<br/>helpers<br/>[index.ts]"]
  node_shared_wasm["WASM math<br/>rust wasm<br/>[lib.rs]"]
end

subgraph group_infra["Infra"]
  node_infra_compose["Compose<br/>local dev<br/>[docker-compose.yml]"]
  node_infra_k8s["Kubernetes<br/>deploy manifests<br/>[kustomization.yaml]"]
  node_infra_tf["Terraform<br/>cloud infra<br/>[.gitkeep]"]
  node_cicd["CI/CD<br/>pipeline<br/>[build.yaml]"]
end

node_external_git(("Git providers<br/>external system"))
node_external_github(("GitHub OAuth<br/>external identity"))

node_frontend_app -->|"renders"| node_frontend_canvas
node_frontend_app -->|"shows details"| node_frontend_commit_panel
node_frontend_canvas -->|"uses"| node_frontend_node_engine
node_frontend_canvas -->|"drives viewport"| node_frontend_view
node_frontend_node_engine -->|"calls math"| node_frontend_math
node_frontend_app -->|"state"| node_frontend_store
node_frontend_app -->|"collab state"| node_frontend_crdt
node_frontend_app -->|"fetches data"| node_frontend_api
node_frontend_api -->|"REST"| node_backend_api
node_frontend_crdt -->|"syncs"| node_backend_ws
node_backend_api -->|"guards"| node_backend_middleware
node_backend_api -->|"loads topology"| node_backend_gitengine
node_backend_api -->|"queries"| node_backend_search
node_backend_api -->|"reads/writes"| node_backend_db
node_backend_api -->|"serializes"| node_backend_models
node_backend_api -->|"coordination"| node_backend_ws
node_backend_auth -->|"OAuth"| node_external_github
node_backend_auth -->|"issues JWT"| node_backend_api
node_backend_crypto -->|"protects"| node_backend_secrets
node_backend_secrets -->|"stores encrypted config"| node_backend_db
node_backend_db -->|"persists"| node_backend_models
node_backend_ws -->|"realtime updates"| node_frontend_crdt
node_backend_gitengine -->|"reads mirrors"| node_external_git
node_worker_app -->|"enriches"| node_backend_db
node_worker_app -->|"publishes links"| node_backend_api
node_shared_types -.->|"contracts"| node_frontend_api
node_shared_types -.->|"mirrors"| node_backend_models
node_shared_utils -.->|"helpers"| node_frontend_view
node_shared_wasm -.->|"implements"| node_frontend_math
node_infra_compose -.->|"local run"| node_backend_api
node_infra_compose -.->|"local run"| node_frontend_app
node_infra_k8s -.->|"deploys"| node_backend_api
node_infra_k8s -.->|"deploys"| node_frontend_app
node_infra_k8s -.->|"deploys"| node_backend_db
node_infra_tf -.->|"provisions"| node_infra_k8s
node_cicd -.->|"releases"| node_infra_k8s
node_cicd -.->|"builds"| node_worker_app

click node_frontend_app "https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/App.tsx"
click node_frontend_canvas "https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/components/Canvas.tsx"
click node_frontend_node_engine "https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/components/NodeEngine.tsx"
click node_frontend_commit_panel "https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/components/CommitPanel.tsx"
click node_frontend_api "https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/api/client.ts"
click node_frontend_store "https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/store/useStore.ts"
click node_frontend_crdt "https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/store/useCRDT.ts"
click node_frontend_view "https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/views/viewState.ts"
click node_frontend_math "https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/math/engine.ts"
click node_backend_api "https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/api/router.go"
click node_backend_middleware "https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/api/middleware.go"
click node_backend_gitengine "https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/gitengine/engine.go"
click node_backend_search "https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/search/search.go"
click node_backend_ws "https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/ws/hub.go"
click node_backend_auth "https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/auth/oauth.go"
click node_backend_db "https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/db/db.go"
click node_backend_crypto "https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/crypto/crypto.go"
click node_backend_secrets "https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/secrets/secrets.go"
click node_backend_models "https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/models/models.go"
click node_worker_app "https://github.com/ramin1886/dabiran/blob/main/apps/worker/src/main.rs"
click node_shared_types "https://github.com/ramin1886/dabiran/blob/main/packages/shared-types/src/index.ts"
click node_shared_utils "https://github.com/ramin1886/dabiran/blob/main/packages/utils/src/index.ts"
click node_shared_wasm "https://github.com/ramin1886/dabiran/blob/main/packages/wasm-math/src/lib.rs"
click node_infra_compose "https://github.com/ramin1886/dabiran/blob/main/infra/docker-compose.yml"
click node_infra_k8s "https://github.com/ramin1886/dabiran/blob/main/infra/kubernetes/base/kustomization.yaml"
click node_infra_tf "https://github.com/ramin1886/dabiran/blob/main/infra/terraform/modules/.gitkeep"
click node_cicd "https://github.com/ramin1886/dabiran/blob/main/cicd/build.yaml"

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_frontend_app,node_frontend_canvas,node_frontend_node_engine,node_frontend_commit_panel,node_frontend_api,node_frontend_store,node_frontend_crdt,node_frontend_view,node_frontend_math toneBlue
class node_backend_api,node_backend_middleware,node_backend_gitengine,node_backend_search,node_backend_ws,node_backend_auth,node_backend_db,node_backend_crypto,node_backend_secrets,node_backend_models toneAmber
class node_worker_app toneMint
class node_shared_types,node_shared_utils,node_shared_wasm toneRose
class node_infra_compose,node_infra_k8s,node_infra_tf,node_cicd toneIndigo
class node_external_git,node_external_github toneNeutral
```

## Components

### Frontend

React + PixiJS canvas client

- [Canvas UI](https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/App.tsx): react client · Browser app for graph visualization and collaboration · `apps/frontend/src/App.tsx`
- [Canvas](https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/components/Canvas.tsx): PixiJS view · WebGL canvas rendering and interaction surface · `apps/frontend/src/components/Canvas.tsx`
- [Node engine](https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/components/NodeEngine.tsx): layout/interaction · Graph layout, node behavior, and canvas orchestration · `apps/frontend/src/components/NodeEngine.tsx`
- [Commit panel](https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/components/CommitPanel.tsx): detail sidebar · Side panel for commit and repository details · `apps/frontend/src/components/CommitPanel.tsx`
- [API client](https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/api/client.ts): REST client · Frontend boundary for backend data fetches · `apps/frontend/src/api/client.ts`
- [App state](https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/store/useStore.ts): local state · Client-side UI and application state store · `apps/frontend/src/store/useStore.ts`
- [CRDT state](https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/store/useCRDT.ts): collab state · Shared collaborative document and sync state · `apps/frontend/src/store/useCRDT.ts`
- [View state](https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/views/viewState.ts): viewport state · Zoom, pan, and viewport behavior · `apps/frontend/src/views/viewState.ts`
- [Math engine](https://github.com/ramin1886/dabiran/blob/main/apps/frontend/src/math/engine.ts): WASM helper · Performance-sensitive viewport and canvas math · `apps/frontend/src/math/engine.ts`

### Backend

Go API, auth, persistence, and collaboration

- [HTTP API](https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/api/router.go): Go router · REST surface for repositories, views, search, and links · `apps/backend/src/api/router.go`
- [Middleware](https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/api/middleware.go): auth boundary · Request authentication and authorization enforcement · `apps/backend/src/api/middleware.go`
- [Git engine](https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/gitengine/engine.go): domain engine · Reads and organizes Git history into topology data · `apps/backend/src/gitengine/engine.go`
- [Search](https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/search/search.go): query service · Filtering and lookup over repository graph data · `apps/backend/src/search/search.go`
- [WebSocket hub](https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/ws/hub.go): realtime server · Collaborative session routing and live client coordination · `apps/backend/src/ws/hub.go`
- [Auth](https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/auth/oauth.go): identity · GitHub OAuth and JWT session issuance · `apps/backend/src/auth/oauth.go`
- [Postgres](https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/db/db.go): persistence · Durable storage for users, teams, repositories, and annotations · `apps/backend/src/db/db.go`
- [Crypto](https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/crypto/crypto.go): encryption · AES-GCM encryption and master-key handling · `apps/backend/src/crypto/crypto.go`
- [Secrets](https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/secrets/secrets.go): secret mgmt · Protected secret storage and retrieval · `apps/backend/src/secrets/secrets.go`
- [Models](https://github.com/ramin1886/dabiran/blob/main/apps/backend/src/models/models.go): data model · Backend domain objects and wire structures · `apps/backend/src/models/models.go`

### Worker

Rust async dependency processor

- [Dep worker](https://github.com/ramin1886/dabiran/blob/main/apps/worker/src/main.rs): Rust service · Async manifest parsing and dependency-link generation · `apps/worker/src/main.rs`

### Shared

Cross-app contracts and performance helpers

- [Shared types](https://github.com/ramin1886/dabiran/blob/main/packages/shared-types/src/index.ts): contracts · Cross-app TypeScript contracts mirroring backend payloads · `packages/shared-types/src/index.ts`
- [Utils](https://github.com/ramin1886/dabiran/blob/main/packages/utils/src/index.ts): helpers · Shared pure helpers such as hashing and viewport utilities · `packages/utils/src/index.ts`
- [WASM math](https://github.com/ramin1886/dabiran/blob/main/packages/wasm-math/src/lib.rs): rust wasm · Reusable WebAssembly math module for canvas performance · `packages/wasm-math/src/lib.rs`

### Infra

Container, Kubernetes, and Terraform delivery

- [Compose](https://github.com/ramin1886/dabiran/blob/main/infra/docker-compose.yml): local dev · Containerized local development stack · `infra/docker-compose.yml`
- [Kubernetes](https://github.com/ramin1886/dabiran/blob/main/infra/kubernetes/base/kustomization.yaml): deploy manifests · Base and production deployment manifests · `infra/kubernetes/base/kustomization.yaml`
- [Terraform](https://github.com/ramin1886/dabiran/blob/main/infra/terraform/modules/.gitkeep): cloud infra · Cloud infrastructure scaffolding · `infra/terraform/modules/.gitkeep`
- [CI/CD](https://github.com/ramin1886/dabiran/blob/main/cicd/build.yaml): pipeline · Build, test, and deploy automation · `cicd/build.yaml`

### Other components

- **Git providers**: external system · Upstream Git hosting and mirrored repository sources
- **GitHub OAuth**: external identity · Upstream identity provider for login

## Connections

- Canvas UI → Canvas: renders
- Canvas UI → Commit panel: shows details
- Canvas → Node engine: uses
- Canvas → View state: drives viewport
- Node engine → Math engine: calls math
- Canvas UI → App state: state
- Canvas UI → CRDT state: collab state
- Canvas UI → API client: fetches data
- API client → HTTP API: REST
- CRDT state → WebSocket hub: syncs
- HTTP API → Middleware: guards
- HTTP API → Git engine: loads topology
- HTTP API → Search: queries
- HTTP API → Postgres: reads/writes
- HTTP API → Models: serializes
- HTTP API → WebSocket hub: coordination
- Auth → GitHub OAuth: OAuth
- Auth → HTTP API: issues JWT
- Crypto → Secrets: protects
- Secrets → Postgres: stores encrypted config
- Postgres → Models: persists
- WebSocket hub → CRDT state: realtime updates
- Git engine → Git providers: reads mirrors
- Dep worker → Postgres: enriches
- Dep worker → HTTP API: publishes links
- Shared types → API client: contracts
- Shared types → Models: mirrors
- Utils → View state: helpers
- WASM math → Math engine: implements
- Compose → HTTP API: local run
- Compose → Canvas UI: local run
- Kubernetes → HTTP API: deploys
- Kubernetes → Canvas UI: deploys
- Kubernetes → Postgres: deploys
- Terraform → Kubernetes: provisions
- CI/CD → Kubernetes: releases
- CI/CD → Dep worker: builds