# jeet2005/nexsync architecture

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

- Interactive diagram: https://gitdiagram.com/jeet2005/nexsync
- Repository: https://github.com/jeet2005/nexsync

## Overview

NexSync is a collaborative writing app: users sign in, create or open a shared document, edit together, and optionally request a reviewable AI rewrite. The React app hosts the TipTap/Yjs editor, sends updates over WebSockets, and receives presence; FastAPI authenticates users, enforces document access, and persists collaboration state in PostgreSQL, with Redis for cross-instance fanout. Sharing, revision history, snapshots, and AI suggestions are additional capabilities. Source excerpts show key entry points, but not every route or persistence operation; README evidence supports the broader feature branches.

Main entry points: [`frontend/src/App.tsx`](https://github.com/jeet2005/nexsync/blob/main/frontend/src/App.tsx) (App and editor), [`backend/app/main.py`](https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py) (Document API), [`backend/app/db.py`](https://github.com/jeet2005/nexsync/blob/main/backend/app/db.py) (Database session), [`frontend/src/firebase.ts`](https://github.com/jeet2005/nexsync/blob/main/frontend/src/firebase.ts) (Firebase client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Writing client"]
  node_app["App and editor<br/>[App.tsx]"]
  node_firebase_client["Firebase client<br/>[firebase.ts]"]
  node_stale_guard["Stale-edit guard<br/>[conflict.ts]"]
end

subgraph group_api["API and identity"]
  node_document_api["Document API<br/>[main.py]"]
  node_identity["Token verification<br/>[auth.py]"]
  node_presence_access["Presence access grant<br/>[presence.py]"]
  node_ai["AI proposals<br/>[main.py]"]
  node_sharing["Document sharing<br/>[main.py]"]
  node_history["Revision history<br/>[main.py]"]
end

subgraph group_collab["Collaboration runtime"]
  node_socket["WebSocket collaboration<br/>[main.py]"]
  node_relay["Redis event relay<br/>[main.py]"]
  node_compactor["Snapshot compaction<br/>[main.py]"]
end

subgraph group_storage["Durable state"]
  node_data_models["Document data model<br/>[models.py]"]
  node_db_session["Database session<br/>[db.py]"]
end

subgraph group_integrations["External services"]
  node_postgres[("PostgreSQL")]
  node_firebase_auth["Firebase Auth"]
  node_firebase_presence[("Realtime Database")]
  node_redis["Redis Pub/Sub"]
  node_ai_provider["AI provider"]
end

node_writer(("Writer"))

node_writer -->|"edits and requests"| node_app
node_app -->|"uses"| node_firebase_client
node_app -->|"calls document APIs"| node_document_api
node_app -->|"exchanges Yjs updates"| node_socket
node_app -->|"tracks presence"| node_firebase_presence
node_firebase_client -->|"initializes auth"| node_firebase_auth
node_firebase_client -->|"initializes database"| node_firebase_presence
node_document_api -->|"verifies requests"| node_identity
node_document_api -->|"queries and writes"| node_db_session
node_document_api -->|"grants access"| node_presence_access
node_document_api -->|"handles sharing"| node_sharing
node_document_api -->|"serves revisions"| node_history
node_document_api -->|"handles proposals"| node_ai
node_identity -->|"verifies identity"| node_firebase_auth
node_presence_access -->|"writes access grant"| node_firebase_presence
node_socket -->|"authenticates connection"| node_identity
node_socket -->|"persists updates"| node_db_session
node_socket -->|"publishes events"| node_relay
node_relay -->|"publishes and subscribes"| node_redis
node_socket -->|"triggers compaction"| node_compactor
node_compactor -->|"stores snapshots"| node_db_session
node_db_session -->|"uses mapped entities"| node_data_models
node_db_session -->|"stores durable state"| node_postgres
node_ai -->|"requests completion"| node_ai_provider
node_ai -->|"returns proposal"| node_app
node_app -->|"checks target text"| node_stale_guard
node_stale_guard -->|"permits unchanged edits"| node_app
node_app -->|"loads revision history"| node_history

click node_app "https://github.com/jeet2005/nexsync/blob/main/frontend/src/App.tsx"
click node_firebase_client "https://github.com/jeet2005/nexsync/blob/main/frontend/src/firebase.ts"
click node_stale_guard "https://github.com/jeet2005/nexsync/blob/main/frontend/src/conflict.ts"
click node_document_api "https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py"
click node_identity "https://github.com/jeet2005/nexsync/blob/main/backend/app/auth.py"
click node_presence_access "https://github.com/jeet2005/nexsync/blob/main/backend/app/presence.py"
click node_socket "https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py"
click node_relay "https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py"
click node_compactor "https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py"
click node_ai "https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py"
click node_sharing "https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py"
click node_history "https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py"
click node_data_models "https://github.com/jeet2005/nexsync/blob/main/backend/app/models.py"
click node_db_session "https://github.com/jeet2005/nexsync/blob/main/backend/app/db.py"

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_app,node_firebase_client,node_stale_guard toneBlue
class node_document_api,node_identity,node_presence_access,node_ai,node_sharing,node_history toneAmber
class node_socket,node_relay,node_compactor toneMint
class node_data_models,node_db_session toneRose
class node_postgres,node_firebase_auth,node_firebase_presence,node_redis,node_ai_provider,node_writer toneIndigo
```

## Components

### Writing client

- [App and editor](https://github.com/jeet2005/nexsync/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Firebase client](https://github.com/jeet2005/nexsync/blob/main/frontend/src/firebase.ts): `frontend/src/firebase.ts`
- [Stale-edit guard](https://github.com/jeet2005/nexsync/blob/main/frontend/src/conflict.ts): `frontend/src/conflict.ts`

### API and identity

- [Document API](https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py): `backend/app/main.py`
- [Token verification](https://github.com/jeet2005/nexsync/blob/main/backend/app/auth.py): `backend/app/auth.py`
- [Presence access grant](https://github.com/jeet2005/nexsync/blob/main/backend/app/presence.py): `backend/app/presence.py`
- [AI proposals](https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py): `backend/app/main.py`
- [Document sharing](https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py): `backend/app/main.py`
- [Revision history](https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py): `backend/app/main.py`

### Collaboration runtime

- [WebSocket collaboration](https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py): `backend/app/main.py`
- [Redis event relay](https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py): `backend/app/main.py`
- [Snapshot compaction](https://github.com/jeet2005/nexsync/blob/main/backend/app/main.py): `backend/app/main.py`

### Durable state

- [Document data model](https://github.com/jeet2005/nexsync/blob/main/backend/app/models.py): `backend/app/models.py`
- [Database session](https://github.com/jeet2005/nexsync/blob/main/backend/app/db.py): `backend/app/db.py`

### External services

- **PostgreSQL**
- **Firebase Auth**
- **Realtime Database**
- **Redis Pub/Sub**
- **AI provider**

### Other components

- **Writer**

## Connections

- Writer → App and editor: edits and requests (evidence: `README.md`)
- App and editor → Firebase client: uses (evidence: `frontend/src/App.tsx`)
- App and editor → Document API: calls document APIs (evidence: `frontend/src/App.tsx`)
- App and editor → WebSocket collaboration: exchanges Yjs updates (evidence: `README.md`)
- App and editor → Realtime Database: tracks presence (evidence: `frontend/src/App.tsx`)
- Firebase client → Firebase Auth: initializes auth (evidence: `frontend/src/firebase.ts`)
- Firebase client → Realtime Database: initializes database (evidence: `frontend/src/firebase.ts`)
- Document API → Token verification: verifies requests (evidence: `backend/app/main.py`)
- Document API → Database session: queries and writes (evidence: `backend/app/main.py`)
- Document API → Presence access grant: grants access (evidence: `backend/app/main.py`)
- Document API → Document sharing: handles sharing (evidence: `README.md`)
- Document API → Revision history: serves revisions (evidence: `README.md`)
- Document API → AI proposals: handles proposals (evidence: `backend/app/main.py`)
- Token verification → Firebase Auth: verifies identity (evidence: `backend/app/auth.py`)
- Presence access grant → Realtime Database: writes access grant (evidence: `backend/app/presence.py`)
- WebSocket collaboration → Token verification: authenticates connection (evidence: `backend/app/main.py`)
- WebSocket collaboration → Database session: persists updates (evidence: `README.md`)
- WebSocket collaboration → Redis event relay: publishes events (evidence: `backend/app/main.py`)
- Redis event relay → Redis Pub/Sub: publishes and subscribes (evidence: `backend/app/main.py`)
- WebSocket collaboration → Snapshot compaction: triggers compaction (evidence: `backend/app/main.py`)
- Snapshot compaction → Database session: stores snapshots (evidence: `backend/app/main.py`)
- Database session → Document data model: uses mapped entities (evidence: `backend/app/main.py`)
- Database session → PostgreSQL: stores durable state (evidence: `README.md`)
- AI proposals → AI provider: requests completion (evidence: `backend/app/main.py`)
- AI proposals → App and editor: returns proposal (evidence: `README.md`)
- App and editor → Stale-edit guard: checks target text (evidence: `frontend/src/App.tsx`)
- Stale-edit guard → App and editor: permits unchanged edits (evidence: `frontend/src/conflict.ts`)
- App and editor → Revision history: loads revision history (evidence: `README.md`)
