adityaphasu/notion-clone

<explanation>

Below is a step‑by‑step guide for drawing a clear, accurate system design diagram for Zotion, tailored to its Next.js/Convex/Edgestore/Clerk stack.

1. Identify the project type and purpose

• Full‑stack web application: a Notion‑style note‑taking and organization tool.

• Frontend: Next.js 13 App Router, React, TypeScript, Tailwind, shadcn‑ui, Blocknote editor.

• Backend: Convex real‑time database, Edgestore distributed key–value store (for files/images), Clerk authentication.

2. Analyze the file structure for architectural cues

• app/ – Next.js “app” directory with three primary route groups:

– (landing): public marketing pages

– (main): authenticated workspace pages (documents, sidebar, editor)

– (public): published note previews

• app/api/edgestore/route.ts – custom API route to proxy file uploads/downloads to Edgestore

• convex/ – Convex server functions, schema, generated clients for real‑time data ops

• components/ – shared UI and modal components used by pages

• lib/edgestore.ts – helper to communicate with Edgestore

• hooks/ – React hooks (e.g., useSearch, useSettings) for state & API logic

• next.config.mjs, tailwind.config.ts, tsconfig.json – framework & build configurations

3. Extract additional insights from the README

• Real‑time collaboration via Convex

• File storage with Edgestore (upload, delete, replace)

• Authentication via Clerk

• Publishing flow: private workspace → public preview pages

4. Main components to represent in your diagram

1. User’s Web Browser / Client

– Renders React pages, uses editor, triggers API calls

2. Next.js Frontend (Vercel / Node.js server)

– App Router routes: landing, main (authenticated), public (preview)

– UI: shadcn/ui components, Blocknote editor, modals, theme provider

– API layer:

a. Convex client (via convex/_generated) → real‑time database

b. /api/edgestore route → Edgestore

c. Clerk SDK → authentication flow

3. Convex Real‑Time Database

– Data model (convex/schema.ts), server functions (convex/documents.ts)

– WebSocket/long‑poll for instant updates

4. Edgestore Service

– External file store for images/files, accessed via API route

5. Clerk Authentication Service

– User identity, session tokens, secure API middleware

6. Vercel Hosting

– Deployment platform for Next.js and API routes

5. Relationships and interactions

• Browser → Next.js frontend (HTTP/HTTPS): page loads, form submissions, real‑time socket

• Frontend → Clerk: sign‑in, token validation

• Frontend ↔ Convex: queries, real‑time subscriptions, mutations

• Frontend → /api/edgestore → Edgestore: file upload/download

• Next.js build/deploy → Vercel

6. Architectural patterns and design principles

• Monolithic full‑stack app with clear separation of concerns:

– Presentation (app/ & components/)

– Business logic (hooks/, convex/)

– Data layer (Convex schema + Edgestore)

• Next.js App Router for folder‑based routing and layouts

• Real‑time pub/sub pattern via Convex WS

• API façade for external service (Edgestore) to encapsulate credentials and logic

7. Diagram‐tailoring guidelines for full‑stack apps

• Draw separate layers: Client, Next.js Server, Data Services, External Services

• Emphasize the App Router’s three route groups (landing, main workspace, public preview)

• Show state flow:

– Document creation/edit → Convex → updates propagate to other clients

– Image upload → Edgestore → URL returned → stored in Convex record

• Include deployment context (Vercel)

8. Visual elements to include

• Clear labels for each component (e.g., “Convex Real‑Time DB”, “Edgestore API”)

• Directional arrows for data flow and dependencies

• Color coding or distinct shapes:

– Frontend (e.g., green boxes),

– Backend services (e.g., blue),

– External services (e.g., orange)

• Annotations for key technologies on each component

9. Level of detail

• Don’t omit small yet crucial pieces:

– the /api/edgestore proxy,

– Convex’s generated client code,

– Clerk middleware in Next.js.

• Represent each internal folder (app/, convex/, components/, hooks/, lib/) as logical subcomponents if space allows.

• Capture real‑time vs. request/response flows distinctly (e.g., solid vs. dashed arrows).

By following this structure, you’ll produce a comprehensive system design diagram that reflects both the high‑level architecture and the nitty‑gritty details critical to Zotion’s functionality. Happy diagramming!

</explanation>