# alshakaa11ozil-ops/cloudteams architecture

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

- Interactive diagram: https://gitdiagram.com/alshakaa11ozil-ops/cloudteams
- Repository: https://github.com/alshakaa11ozil-ops/cloudteams

## Overview

1. **Top-level shape**
   - This is a two-app monorepo: `backend` for the API/runtime and `frontend` for the SPA client.
   - Supporting assets include Prisma migrations/schema, a Postman collection, and a persistent `uploads/` area for stored files.

2. **Frontend boundary**
   - The client is a **React + TypeScript + Vite** single-page app.
   - It is organized around authenticated app pages (`FileBrowser`, `DocumentEditor`, `TeamDashboard`, `RecycleBin`, analytics/activity/settings pages) plus a public share entrypoint (`pages/share/PublicSharePage.tsx`).
   - The frontend talks to the backend through dedicated API clients (`axios.ts`, `publicAxios.ts`) and socket hooks/clients for realtime features.

3. **Backend application structure**
   - The backend follows a classic **controller → service → route** layering under `src/`.
   - `routes/` defines HTTP endpoints, `controllers/` handle request/response flow, and `services/` contain domain logic.
   - Shared cross-cutting concerns live in `middleware/`, `config/`, and `utils/`.

4. **Identity, auth, and access control**
   - Authentication is handled by `auth.controller.ts`, `auth.service.ts`, and `auth.middleware.ts`.
   - The system includes **two-factor authentication** (`twoFactor.*`) and role-based/team-based authorization (`requireRole.ts`, `teamGuard.ts`).
   - Team membership, invite codes, and join flows are first-class concepts, not just metadata.

5. **Core domain model**
   - The main business objects are **teams, folders, files, documents, document versions, comments, shares, locks, announcements, and activity events**.
   - Routes/controllers exist for each of these domains, indicating the app is a team-based collaborative storage/document platform rather than a generic file bucket.
   - Soft delete is explicitly supported for folders and comments, which feeds into the recycle bin workflow.

6. **File storage and document lifecycle**
   - File upload handling is wired through `multer` config and a dedicated `storage.service.ts`.
   - The backend persists uploaded content in `backend/uploads/`, so file storage is local/filesystem-backed rather than purely object-storage-backed in this repo.
   - `fileEncryption.ts` and `hash.ts` suggest content protection plus deduplication/content identity logic; the README’s “deduplication” aligns with this.

7. **Realtime collaboration and locking**
   - Collaboration is split across two realtime mechanisms:
     - `collaboration/hocuspocus.ts` for the rich-text collaborative editor
     - `socket.ts` plus `config/socketEvents.ts` for app-wide realtime events
   - The frontend’s editor components (`CollaborativeEditor`, `PresenceBar`, `LockBanner`, version history panel) indicate live presence, soft locking, and concurrent editing support.
   - The lock subsystem is a separate domain, not just UI state.

8. **AI-assisted features**
   - There is a dedicated AI subsystem under `src/services/AI/`.
   - It includes file summaries, analytics summaries, digests, editor assist, duplicate explanation, and caching.
   - `gemini.ts` shows an external LLM provider integration; this is a backend-mediated dependency, likely used by the editor and reporting features.

9. **Search, analytics, and activity**
   - `search`, `analytics`, and `activity` are separate subsystems with their own routes, controllers, and services.
   - Activity logging is also supported by utility code, suggesting most user actions are captured centrally and reused by feeds, audit views, and AI summaries.
   - Announcements and digest generation imply scheduled or periodic communication to team members.

10. **Background jobs and scheduling**
   - `cron.ts` indicates scheduled backend work, likely for digests, cleanup, or periodic notifications.
   - This is important architecturally because not all user-visible behavior is request-driven; some state changes are time-based.

11. **Persistence and schema evolution**
   - Prisma is the data layer (`schema.prisma`, `prisma.config.ts`, and multiple migrations).
   - The migration history shows the schema evolved around announcements, 2FA secrets, soft delete, comments, file versions, and a larger expansion of tables in 2026.
   - For diagramming, the primary persistent store should be shown as the Prisma-managed database, with the filesystem as a second storage boundary for uploaded documents.

12. **Deployment/runtime signals**
   - The backend has a `Dockerfile`, so it is container-ready.
   - The frontend has `vercel.json`, suggesting deployment as a static SPA on Vercel or a similar edge/static host.
   - Operationally, the repo exposes a clear split: browser SPA, API/realtime backend, database, local file storage, and external AI service.

13. **Main end-to-end flow**
   - A typical request path is: user interacts with the React app → frontend calls REST endpoints or websocket channels → backend authenticates/authorizes → services read/write Prisma data and upload storage → responses update the UI.
   - For editing, the path expands to include realtime collaboration and lock/presence synchronization.
   - For AI-powered actions, the backend additionally calls the Gemini-based service layer and returns cached or generated results.

14. **What to emphasize in an architecture diagram**
   - Show the repo as a **collaborative team document/file platform** with these boundaries: client SPA, REST API, realtime collaboration layer, database, file storage, and external AI provider.
   - Treat authentication/2FA, sharing, locking, versioning, and recycle bin as core business subsystems, not supporting details.

Main entry points: [`backend/src/routes`](https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/backend/src/routes) (HTTP routes), [`backend/prisma/schema.prisma`](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/prisma/schema.prisma) (Prisma DB), [`backend/src/services/document.service.ts`](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/services/document.service.ts) (Documents), [`frontend/src/pages`](https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/frontend/src/pages) (App pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_frontend["Frontend SPA"]
  node_frontend_app["SPA client<br/>react vite app<br/>[App.tsx]"]
  node_frontend_pages["App pages<br/>authenticated views"]
  node_frontend_public["Public share<br/>public view"]
  node_frontend_api["API clients<br/>rest clients"]
  node_frontend_realtime["Realtime hooks<br/>socket hooks"]
  node_frontend_editor["Editor UI<br/>collab editor"]
end

subgraph group_grp_backend["Backend API"]
  node_backend_server["API server<br/>runtime entrypoint<br/>[server.ts]"]
  node_backend_routes["HTTP routes<br/>route layer"]
  node_backend_auth["Auth & 2FA<br/>identity layer<br/>[auth.controller.ts]"]
  node_backend_team["Teams & invites<br/>membership layer<br/>[teamController.ts]"]
  node_backend_files["Files & folders<br/>content layer<br/>[file.service.ts]"]
  node_backend_docs["Documents<br/>document layer"]
  node_backend_collab["Realtime layer<br/>collaboration runtime<br/>[hocuspocus.ts]"]
  node_backend_ai["AI services<br/>llm integration"]
  node_backend_activity["Activity & analytics<br/>insight layer"]
  node_backend_search["Search<br/>query layer<br/>[search.service.ts]"]
  node_backend_recycle["Recycle bin<br/>soft-delete flow"]
end

subgraph group_grp_data["Data & Storage"]
  node_backend_prisma[("Prisma DB<br/>database schema<br/>[schema.prisma]")]
  node_backend_uploads[("Uploads store<br/>filesystem")]
end

subgraph group_grp_external["External Services"]
  node_external_gemini{{"Gemini API<br/>llm provider"}}
end

node_frontend_app -->|"renders"| node_frontend_pages
node_frontend_app -->|"routes"| node_frontend_public
node_frontend_pages -->|"calls"| node_frontend_api
node_frontend_pages -->|"subscribes"| node_frontend_realtime
node_frontend_editor -->|"syncs"| node_frontend_realtime
node_frontend_editor -->|"loads"| node_frontend_api
node_frontend_api -->|"requests"| node_backend_routes
node_frontend_realtime -->|"ws"| node_backend_collab
node_backend_server -->|"mounts"| node_backend_routes
node_backend_routes -->|"auth"| node_backend_auth
node_backend_routes -->|"teams"| node_backend_team
node_backend_routes -->|"files"| node_backend_files
node_backend_routes -->|"documents"| node_backend_docs
node_backend_routes -->|"feeds"| node_backend_activity
node_backend_routes -->|"search"| node_backend_search
node_backend_routes -->|"restore"| node_backend_recycle
node_backend_docs -->|"collaborates"| node_backend_collab
node_backend_docs -->|"assists"| node_backend_ai
node_backend_ai -->|"invokes"| node_external_gemini
node_backend_files -->|"persists"| node_backend_prisma
node_backend_docs -->|"persists"| node_backend_prisma
node_backend_activity -->|"records"| node_backend_prisma
node_backend_files -->|"stores"| node_backend_uploads
node_backend_recycle -->|"reads/writes"| node_backend_prisma
node_backend_auth -->|"verifies"| node_backend_prisma

click node_frontend_app "https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/frontend/src/App.tsx"
click node_frontend_pages "https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/frontend/src/pages"
click node_frontend_public "https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/frontend/src/pages/share/PublicSharePage.tsx"
click node_frontend_api "https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/frontend/src/api"
click node_frontend_realtime "https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/frontend/src/hooks"
click node_frontend_editor "https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/frontend/src/components/editor"
click node_backend_server "https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/server.ts"
click node_backend_routes "https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/backend/src/routes"
click node_backend_auth "https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/controllers/auth.controller.ts"
click node_backend_team "https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/controllers/teamController.ts"
click node_backend_files "https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/services/file.service.ts"
click node_backend_docs "https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/services/document.service.ts"
click node_backend_collab "https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/collaboration/hocuspocus.ts"
click node_backend_ai "https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/backend/src/services/AI"
click node_backend_activity "https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/services/activity.service.ts"
click node_backend_search "https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/services/search.service.ts"
click node_backend_recycle "https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/services/recycleBin.service.ts"
click node_backend_prisma "https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/prisma/schema.prisma"
click node_backend_uploads "https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/backend/uploads"

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_pages,node_frontend_public,node_frontend_api,node_frontend_realtime,node_frontend_editor toneBlue
class node_backend_server,node_backend_routes,node_backend_auth,node_backend_team,node_backend_files,node_backend_docs,node_backend_collab,node_backend_ai,node_backend_activity,node_backend_search,node_backend_recycle toneAmber
class node_backend_prisma,node_backend_uploads toneMint
class node_external_gemini toneRose
```

## Components

### Frontend SPA

React/Vite client for authenticated teamwork and public sharing

- [SPA client](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/frontend/src/App.tsx): react vite app · Single-page client shell and route entrypoint · `frontend/src/App.tsx`
- [App pages](https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/frontend/src/pages): authenticated views · File browser, document editor, team dashboard, recycle bin, analytics, activity, and settings · `frontend/src/pages`
- [Public share](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/frontend/src/pages/share/PublicSharePage.tsx): public view · Unauthenticated shared-document entrypoint · `frontend/src/pages/share/PublicSharePage.tsx`
- [API clients](https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/frontend/src/api): rest clients · Axios wrappers for authenticated and public backend calls · `frontend/src/api`
- [Realtime hooks](https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/frontend/src/hooks): socket hooks · Socket client and team/lock synchronization hooks · `frontend/src/hooks`
- [Editor UI](https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/frontend/src/components/editor): collab editor · Collaborative editor, presence, locking, AI assist, and version history panels · `frontend/src/components/editor`

### Backend API

Express-style API, realtime collaboration, and domain services

- [API server](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/server.ts): runtime entrypoint · Backend process bootstrap and route composition · `backend/src/server.ts`
- [HTTP routes](https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/backend/src/routes): route layer · Endpoint mapping for auth, teams, files, documents, shares, search, analytics, and activity · `backend/src/routes`
- [Auth & 2FA](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/controllers/auth.controller.ts): identity layer · Authentication, sessions/JWT, two-factor flows, and access middleware · `backend/src/controllers/auth.controller.ts`
- [Teams & invites](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/controllers/teamController.ts): membership layer · Team lifecycle, invites, join flow, and role-based guards · `backend/src/controllers/teamController.ts`
- [Files & folders](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/services/file.service.ts): content layer · File upload, folder management, storage, hashing, and encryption · `backend/src/services/file.service.ts`
- [Documents](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/services/document.service.ts): document layer · Document CRUD, comments, versions, sharing, and locks · `backend/src/services/document.service.ts`
- [Realtime layer](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/collaboration/hocuspocus.ts): collaboration runtime · Hocuspocus collaboration and app-wide socket events · `backend/src/collaboration/hocuspocus.ts`
- [AI services](https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/backend/src/services/AI): llm integration · File summaries, analytics summaries, digests, editor assist, duplicate explanation, and cache · `backend/src/services/AI`
- [Activity & analytics](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/services/activity.service.ts): insight layer · Activity logging, feeds, analytics, and digest generation · `backend/src/services/activity.service.ts`
- [Search](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/services/search.service.ts): query layer · Repository-wide search endpoints and service · `backend/src/services/search.service.ts`
- [Recycle bin](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/src/services/recycleBin.service.ts): soft-delete flow · Restoration and deletion workflow for soft-deleted folders and comments · `backend/src/services/recycleBin.service.ts`

### Data & Storage

Database and filesystem persistence boundaries

- [Prisma DB](https://github.com/alshakaa11ozil-ops/cloudteams/blob/main/backend/prisma/schema.prisma): database schema · Prisma-managed relational persistence and migrations · `backend/prisma/schema.prisma`
- [Uploads store](https://github.com/alshakaa11ozil-ops/cloudteams/tree/main/backend/uploads): filesystem · Persistent local file storage for uploaded documents · `backend/uploads`

### External Services

Third-party provider integrations

- **Gemini API**: llm provider · External model used by backend AI features

## Connections

- SPA client → App pages: renders · Client routes to authenticated app pages
- SPA client → Public share: routes · Client exposes public share entrypoint
- App pages → API clients: calls · Pages use REST clients for data operations
- App pages → Realtime hooks: subscribes · Pages connect to socket and lock/team hooks
- Editor UI → Realtime hooks: syncs · Editor presence and lock state are realtime-driven
- Editor UI → API clients: loads · Editor fetches document data and saves changes
- API clients → HTTP routes: requests · REST traffic targets backend routes
- Realtime hooks → Realtime layer: ws · Editor collaboration uses realtime backend channels
- API server → HTTP routes: mounts · Server composes route layer
- HTTP routes → Auth & 2FA: auth · Login, register, and 2FA endpoints
- HTTP routes → Teams & invites: teams · Team membership, invite, and join endpoints
- HTTP routes → Files & folders: files · File and folder endpoints
- HTTP routes → Documents: documents · Document, comment, version, share, and lock endpoints
- HTTP routes → Activity & analytics: feeds · Activity and analytics endpoints
- HTTP routes → Search: search · Search endpoints
- HTTP routes → Recycle bin: restore · Recycle bin endpoints
- Documents → Realtime layer: collaborates · Document editing bridges to collaboration runtime
- Documents → AI services: assists · Editor assist and document intelligence flows
- AI services → Gemini API: invokes · LLM-backed generation and summarization
- Files & folders → Prisma DB: persists · Metadata, teams, files, comments, versions, and locks are stored in Prisma database
- Documents → Prisma DB: persists · Document state and version history live in the database
- Activity & analytics → Prisma DB: records · Events and summaries are stored for feeds and analytics
- Files & folders → Uploads store: stores · Uploaded content is written to local filesystem storage
- Recycle bin → Prisma DB: reads/writes · Soft-deleted records and restore state are managed in the database
- Auth & 2FA → Prisma DB: verifies · Identity and 2FA state are persisted and checked against the database
