# debojyotimishra/atlas architecture

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

- Interactive diagram: https://gitdiagram.com/debojyotimishra/atlas
- Repository: https://github.com/debojyotimishra/atlas

## Overview

##### Project type and purpose
- This is a full-stack, real-time collaboration application (“Atlas”) built on Next.js App Router (v15).
- It provides authenticated document management, image uploads, and real-time editing, using Clerk for auth, Convex for database and real-time subscriptions, and EdgeStore for file storage.

##### File structure
- Top-level “app” directory: Next.js App Router—separate “(marketing)” (static, public-facing pages) and “(main)” (authenticated workspace) routes, plus an “app/api/edgestore” serverless route.
- “convex” directory: Convex backend functions (documents.ts), schema definitions, and generated API bindings.
- “components” and “hooks” directories: UI building blocks, modals, provider wrappers (Clerk, Convex, theme, modal), custom React hooks.
- “lib” directory: helper modules (EdgeStore client, utility functions).
- Config files: next.config.js, tailwind.config.ts, ESLint, TypeScript, PostCSS.

##### Key insights from README
- Features: real-time collaboration (Convex), document management, image uploads (EdgeStore), authentication (Clerk).
- Tech stack confirms frameworks and external services.
- Environment variables show runtime integrations with Clerk, Convex, and EdgeStore.

##### Main components
a. Client (Browser) – the React/Next.js front-end.
b. Next.js Server – SSR/SSG routes (app folder) and serverless API routes (app/api/edgestore).
c. Convex Backend – hosted functions and real-time data store.
d. EdgeStore Service – object/file storage.
e. Clerk Auth Service – user authentication and session management.
f. Internal Libraries – “lib/edgestore.ts” helper, “components/providers” wrappers.

##### Relationships and interactions
- Client ↔ Next.js Server: page requests, SSR, hydration.
- Client ↔ Convex Client SDK: real-time subscriptions, RPC calls to convex functions (documents.ts).
- Next.js Server → Convex Backend: secure server-side function calls (e.g., initial data fetching).
- Client → Next.js Serverless API (/api/edgestore): upload proxies to EdgeStore.
- API Route → EdgeStore Service: authenticated uploads/downloads.
- Client ↔ Clerk: UI login/signup, token exchange; Next.js middleware (implicit) protects “(main)” routes.

##### Architectural patterns and design principles
- Separation of concerns: marketing vs. main workspace in App Router.
- Provider pattern: React context for auth (Clerk), state (Zustand optional), modals, theme, Convex client.
- Serverless edge functions: both Convex and Next.js API routes scale on demand.
- Real-time collaboration via Pub/Sub model in Convex.

- Internal components (Next.js, React components)
- External services (Clerk, EdgeStore, Convex)
- Edges directionally: data flow, control flow, subscription channels.

##### Detailed component breakdown (suggested layers)
Layer 1: User Browser
- React UI under “app/(marketing)” and “app/(main)”
- Hooks and state providers
Layer 2: Next.js Server
- App Router (layout.tsx, page.tsx)
- Serverless API (app/api/edgestore/route.ts)
Layer 3: Convex Backend
- Schema (convex/schema.ts)
- Server functions (convex/documents.ts)
- Generated bindings
Layer 4: Third-Party Services
- Clerk (auth)
- EdgeStore (file store)
- Convex Data Storage

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        Marketing["Marketing Routes"]:::frontend
        Main["Main Workspace Routes"]:::frontend
        Components["UI Components"]:::frontend
        Hooks["React Hooks"]:::frontend
    end
    click Marketing "https://github.com/debojyotimishra/atlas/tree/main/app/(marketing)"
    click Main "https://github.com/debojyotimishra/atlas/tree/main/app/(main)"
    click Components "https://github.com/debojyotimishra/atlas/tree/main/components/"
    click Hooks "https://github.com/debojyotimishra/atlas/tree/main/hooks/"

    %% Next.js Server Layer
    subgraph "Next.js Server"
        direction TB
        Layout["layout.tsx"]:::backend
        Error["error.tsx"]:::backend
        API["Edgestore API Route"]:::backend
    end
    click Layout "https://github.com/debojyotimishra/atlas/blob/main/app/layout.tsx"
    click Error "https://github.com/debojyotimishra/atlas/blob/main/app/error.tsx"
    click API "https://github.com/debojyotimishra/atlas/blob/main/app/api/edgestore/[...edgestore]/route.ts"

    %% Convex Backend Layer
    subgraph "Convex Backend"
        direction TB
        Schema["schema.ts"]:::backend
        Documents["documents.ts"]:::backend
        Generated["_generated bindings"]:::backend
    end
    click Schema "https://github.com/debojyotimishra/atlas/blob/main/convex/schema.ts"
    click Documents "https://github.com/debojyotimishra/atlas/blob/main/convex/documents.ts"
    click Generated "https://github.com/debojyotimishra/atlas/tree/main/convex/_generated/"

    %% Internal Utilities Layer
    subgraph "Internal Utilities"
        direction TB
        EdgeUtil["EdgeStore Client"]:::util
        Utils["Utilities"]:::util
        ConvexProv["convex-provider"]:::util
        ModalProv["modal-provider"]:::util
        ThemeProv["theme-provider"]:::util
    end
    click EdgeUtil "https://github.com/debojyotimishra/atlas/blob/main/lib/edgestore.ts"
    click Utils "https://github.com/debojyotimishra/atlas/blob/main/lib/utils.ts"
    click ConvexProv "https://github.com/debojyotimishra/atlas/blob/main/components/providers/convex-provider.tsx"
    click ModalProv "https://github.com/debojyotimishra/atlas/blob/main/components/providers/modal-provider.tsx"
    click ThemeProv "https://github.com/debojyotimishra/atlas/blob/main/components/providers/theme-provider.tsx"

    %% Upload UI Components
    subgraph "Image Upload UI"
        direction TB
        SingleUpload["single-image-uploader.tsx"]:::frontend
        SingleImage["single-image.tsx"]:::frontend
        Progress["progress-circle.tsx"]:::frontend
        UploaderProv["uploader-provider.tsx"]:::frontend
    end
    click SingleUpload "https://github.com/debojyotimishra/atlas/blob/main/components/upload/single-image-uploader.tsx"
    click SingleImage "https://github.com/debojyotimishra/atlas/blob/main/components/upload/single-image.tsx"
    click Progress "https://github.com/debojyotimishra/atlas/blob/main/components/upload/progress-circle.tsx"
    click UploaderProv "https://github.com/debojyotimishra/atlas/blob/main/components/upload/uploader-provider.tsx"

    %% Shared UI Primitives
    subgraph "UI Primitives"
        direction TB
        UIComp["components/ui/"]:::frontend
        Modals["components/modals/"]:::frontend
        Toolbar["toolbar.tsx"]:::frontend
        SearchCmd["search-command.tsx"]:::frontend
        Spinner["spinner.tsx"]:::frontend
    end
    click UIComp "https://github.com/debojyotimishra/atlas/tree/main/components/ui/"
    click Modals "https://github.com/debojyotimishra/atlas/tree/main/components/modals/"
    click Toolbar "https://github.com/debojyotimishra/atlas/blob/main/components/toolbar.tsx"
    click SearchCmd "https://github.com/debojyotimishra/atlas/blob/main/components/search-command.tsx"
    click Spinner "https://github.com/debojyotimishra/atlas/blob/main/components/spinner.tsx"

    %% Third-Party Services
    subgraph "Third-Party Services"
        direction TB
        Clerk["Clerk Auth Service"]:::external
        EdgeStoreService["EdgeStore Service"]:::external
        ConvexStore["Convex Data Storage"]:::external
    end

    %% Connections
    Marketing -->|"HTTP GET/SSR"| Layout
    Main -->|"HTTP GET/SSR"| Layout
    Components -->|"Convex RPC/WebSocket"| Documents
    Components -->|"Subscriptions"| ConvexStore
    Components -->|"Auth UI"| Clerk
    Layout -->|"Server-side Convex RPC"| Documents
    SingleUpload -->|"POST /api/edgestore"| API
    API -->|"uses EdgeStore client"| EdgeUtil
    API -->|"POST /api/edgestore"| EdgeStoreService
    EdgeStoreService -->|"Store/Retrieve Files"| EdgeUtil
    ConvexProv --> Components
    ModalProv --> Components
    ThemeProv --> Components
    Components --> SingleUpload
    Components --> SingleImage
    Components --> Progress
    Components --> UploaderProv
    Components --> UIComp
    Components --> Modals
    Components --> Toolbar
    Components --> SearchCmd
    Components --> Spinner

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef backend fill:#ffe0b2,stroke:#e65100,color:#bf360c
    classDef external fill:#c8e6c9,stroke:#1b5e20,color:#0d5302
    classDef util fill:#e1bee7,stroke:#4a148c,color:#311b92
```
