# ronakmaheshwari/second-brain architecture

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

- Interactive diagram: https://gitdiagram.com/ronakmaheshwari/second-brain
- Repository: https://github.com/ronakmaheshwari/second-brain

## Overview

##### Project Type & Purpose
- This is a full-stack web application called “Second Brain,” providing personal knowledge management via a React-based SPA frontend and a Node.js/Express backend.
- The backend uses Prisma to interact with a PostgreSQL database (hosted on NeonDB via Supabase), handles authentication with JWT/Zod, and connects to Supabase Storage for file attachments.

##### High-Level Components
a. Client Layer
- Browser / Device (Web & Mobile Friendly)
- React SPA (Vite build) using Tailwind CSS and React components under `frontend/src/ui` and pages under `frontend/src/ui/pages`.
b. API Layer (Backend)
- Express.js server entry point (`backend/src/index.ts`)
- Middleware (authentication, request validation in `backend/src/middleware.ts`)
- Route handlers for:
- /brain (note management)
- /content (CRUD operations + Markdown processing)
- /check (search/tag suggestions)
- /user (signup/signin, JWT issuance)
- Utility modules (`backend/src/utils.ts`) for shared logic (e.g., full-text search helpers).
c. Data Layer
- Prisma ORM (`backend/prisma/schema.prisma`)
- Migrations folder with SQL scripts
- PostgreSQL database on NeonDB (via Supabase)
d. Storage & External Services
- Supabase (Authentication, Database, Storage buckets for sync & backups)
- Vercel (frontend hosting)
- Render.com (backend hosting)

##### Interactions & Data Flow
1. End user interacts with the React SPA in the browser.
2. SPA sends HTTP requests (REST) to Express API endpoints over HTTPS.
3. Express middleware validates JWT/Zod schemas, then routes to the appropriate controller.
4. Controllers invoke Prisma client to read/write in the PostgreSQL database.
5. For file attachments or backups, the backend or frontend directly interfaces with Supabase Storage API.
6. Responses flow back through middleware to the SPA, which renders updated state.
7. Deployment pipelines: frontend pushed to Vercel, backend to Render, with environment variables configured (e.g., SUPABASE_URL, JWT_SECRET).

##### Architectural Patterns & Principles
- Layered architecture (Presentation → API → Business Logic → Data Access).
- Separation of concerns: UI components vs. API routes vs. data models.
- RESTful services with JWT-based auth and schema validation via Zod.
- Infrastructure as code for database schema via Prisma migrations.
- Third-party integration for BaaS (Supabase for DB, Auth, Storage).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User & Client"
        Browser["Browser/Device"]:::ui
    end

    subgraph "Frontend (React SPA)"
        Main["main.tsx"]:::ui
        App["App.tsx"]:::ui
        Config["config.tsx"]:::ui
        Vite["vite.config.ts"]:::ui
        Tailwind["tailwind.config.js"]:::ui
        EnvFE[".env"]:::ui
        StylesCSS["index.css, App.css"]:::ui
        Components["ui/components"]:::ui
        Pages["ui/pages"]:::ui
        Land["Land (Landing Page)"]:::ui
        Signin["signin.tsx"]:::ui
        Signup["signup.tsx"]:::ui
        Dashboard["dashboard.tsx"]:::ui
        Audio["audio.tsx"]:::ui
        Code["code.tsx"]:::ui
        Document["document.tsx"]:::ui
        LinkPage["link.tsx"]:::ui
        Tweet["tweet.tsx"]:::ui
        Video["video.tsx"]:::ui
        SharePage["SharePage.tsx"]:::ui
        PackageFE["package.json"]:::ui
        BuildFE["Vite Build"]:::ui
    end

    subgraph "Backend (Express API)"
        IndexBE["index.ts"]:::api
        Middleware["middleware.ts"]:::api
        subgraph "Routes"
            Brain["brain.ts"]:::api
            Content["content.ts"]:::api
            Check["check.ts"]:::api
            User["user.ts"]:::api
            RoutesIndex["index.ts"]:::api
        end
        Utils["utils.ts"]:::api
        TSConfigBE["tsconfig.json"]:::api
        PackageBE["package.json"]:::api
        subgraph "Build Output"
            DistIndex["index.js"]:::api
            DistMiddleware["middleware.js"]:::api
            DistRoutes["routes/"]:::api
            DistUtils["utils.js"]:::api
        end
        subgraph "Prisma"
            Schema["schema.prisma"]:::data
            Migrations["migrations/"]:::data
        end
    end

    subgraph "Data & External Services"
        Postgres["PostgreSQL DB"]:::data
        SupaAuth["Supabase Auth"]:::ext
        SupaStorage["Supabase Storage"]:::ext
    end

    subgraph "Deployment"
        Vercel["Vercel (Frontend)"]:::deploy
        Render["Render (Backend)"]:::deploy
    end

    Browser -->|"load SPA"| Main
    Main -->|"renders App"| App
    App --> Config
    App --> Components
    App --> Pages
    BuildFE --> App
    Vite --> BuildFE
    App -->|"HTTPS REST"| IndexBE
    IndexBE --> Middleware
    Middleware --> RoutesIndex
    RoutesIndex --> Brain
    RoutesIndex --> Content
    RoutesIndex --> Check
    RoutesIndex --> User
    Brain --> Utils
    Content --> Utils
    Check --> Utils
    User --> Utils
    RoutesIndex --> Schema
    Utils --> Schema
    Schema --> Migrations
    Schema --> Postgres
    IndexBE -->|"S3-style API"| SupaStorage
    App -->|"S3-style API"| SupaStorage
    IndexBE -->|"JWT Auth"| SupaAuth
    App -->|"OAuth/JWT"| SupaAuth
    BuildFE --> Vercel
    DistIndex --> Render

    click Main "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/main.tsx"
    click App "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/App.tsx"
    click Vite "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/vite.config.ts"
    click Tailwind "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/tailwind.config.js"
    click EnvFE "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/.env"
    click StylesCSS "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/index.css"
    click Config "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/config.tsx"
    click Components "https://github.com/ronakmaheshwari/second-brain/tree/main/frontend/src/ui/components"
    click Pages "https://github.com/ronakmaheshwari/second-brain/tree/main/frontend/src/ui/pages"
    click Land "https://github.com/ronakmaheshwari/second-brain/tree/main/frontend/src/ui/pages/Land"
    click Signin "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/ui/pages/signin.tsx"
    click Signup "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/ui/pages/signup.tsx"
    click Dashboard "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/ui/pages/dashboard.tsx"
    click Audio "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/ui/pages/audio.tsx"
    click Code "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/ui/pages/code.tsx"
    click Document "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/ui/pages/document.tsx"
    click LinkPage "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/ui/pages/link.tsx"
    click Tweet "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/ui/pages/tweet.tsx"
    click Video "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/ui/pages/video.tsx"
    click SharePage "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/src/ui/pages/SharePage.tsx"
    click PackageFE "https://github.com/ronakmaheshwari/second-brain/blob/main/frontend/package.json"
    click IndexBE "https://github.com/ronakmaheshwari/second-brain/blob/main/backend/src/index.ts"
    click Middleware "https://github.com/ronakmaheshwari/second-brain/blob/main/backend/src/middleware.ts"
    click Brain "https://github.com/ronakmaheshwari/second-brain/blob/main/backend/src/routes/brain.ts"
    click Content "https://github.com/ronakmaheshwari/second-brain/blob/main/backend/src/routes/content.ts"
    click Check "https://github.com/ronakmaheshwari/second-brain/blob/main/backend/src/routes/check.ts"
    click User "https://github.com/ronakmaheshwari/second-brain/blob/main/backend/src/routes/user.ts"
    click RoutesIndex "https://github.com/ronakmaheshwari/second-brain/blob/main/backend/src/routes/index.ts"
    click Utils "https://github.com/ronakmaheshwari/second-brain/blob/main/backend/src/utils.ts"
    click TSConfigBE "https://github.com/ronakmaheshwari/second-brain/blob/main/backend/tsconfig.json"
    click Schema "https://github.com/ronakmaheshwari/second-brain/blob/main/backend/prisma/schema.prisma"
    click Migrations "https://github.com/ronakmaheshwari/second-brain/tree/main/backend/prisma/migrations"
    click PackageBE "https://github.com/ronakmaheshwari/second-brain/blob/main/backend/package.json"

    classDef ui fill:#cef,stroke:#036;
    classDef api fill:#cfc,stroke:#060;
    classDef data fill:#fdb,stroke:#e85;
    classDef ext fill:#ccc,stroke:#666;
    classDef deploy fill:#eee,stroke:#000,stroke-dasharray: 5 5;
```
