How alshakaa11ozil-ops/cloudteams works
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: routes HTTP routes · schema.prisma Prisma DB · document.service.ts Documents · pages App pages
Components 20
Frontend SPA
React/Vite client for authenticated teamwork and public sharing
- SPA client · Single-page client shell and route entrypoint
frontend/src/App.tsx - App pages · File browser, document editor, team dashboard, recycle bin, analytics, activity, and settings
frontend/src/pages - Public share · Unauthenticated shared-document entrypoint
frontend/src/pages/share/PublicSharePage.tsx - API clients · Axios wrappers for authenticated and public backend calls
frontend/src/api - Realtime hooks · Socket client and team/lock synchronization hooks
frontend/src/hooks - Editor UI · 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 · Backend process bootstrap and route composition
backend/src/server.ts - HTTP routes · Endpoint mapping for auth, teams, files, documents, shares, search, analytics, and activity
backend/src/routes - Auth & 2FA · Authentication, sessions/JWT, two-factor flows, and access middleware
backend/src/controllers/auth.controller.ts - Teams & invites · Team lifecycle, invites, join flow, and role-based guards
backend/src/controllers/teamController.ts - Files & folders · File upload, folder management, storage, hashing, and encryption
backend/src/services/file.service.ts - Documents · Document CRUD, comments, versions, sharing, and locks
backend/src/services/document.service.ts - Realtime layer · Hocuspocus collaboration and app-wide socket events
backend/src/collaboration/hocuspocus.ts - AI services · File summaries, analytics summaries, digests, editor assist, duplicate explanation, and cache
backend/src/services/AI - Activity & analytics · Activity logging, feeds, analytics, and digest generation
backend/src/services/activity.service.ts - Search · Repository-wide search endpoints and service
backend/src/services/search.service.ts - Recycle bin · 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 · Prisma-managed relational persistence and migrations
backend/prisma/schema.prisma - Uploads store · Persistent local file storage for uploaded documents
backend/uploads
External Services
Third-party provider integrations
- Gemini API · External model used by backend AI features
Connections 25
- 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