ramin1886/dabiran

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.