# vanshrana-1004/second-brain architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack “Second-Brain” application.
- Frontend: React + TypeScript SPA built with Vite, styled with Tailwind CSS, uses Axios and localStorage.
- Backend: Node.js + Express REST API, MongoDB for persistence, JWT for authentication.
- Purpose: allow users to save, tag, organize, share, and retrieve links/media snippets from YouTube, Instagram, Twitter, Notion, etc.

##### File structure
- Top-level split into Backend/ and Frontend/ directories.
- Backend/src contains config.ts, db.ts, middleware.ts, util.ts, index.ts → a monolithic Express service following MVC-style separation of concerns.
- Public/static assets in Frontend/public.
- Config files: .env.example, tsconfig.json, Vite config, Tailwind config, ESLint.
- Deployment hints: Frontend/vercel.json, environment variable conventions in README.

##### README insights
- States tech stack, feature set (storage, tagging, sharing, privacy control, responsive UI).
- Emphasizes use of JWT and MongoDB.
- Provides startup instructions and env var definitions, confirming separation of concerns and connection points.

a. Main components
- Client Browser (React SPA)
- Static Asset Server / CDN (Vite dev server in dev, Vercel/Netlify in prod)
- API Server (Express + Node.js)
- Authentication Layer (JWT issuance & verification middleware)
- Database (MongoDB cluster)
- (Optional) External Content Providers – conceptual, since links originate externally
b. Relationships & interactions
- User interacts with React UI → dispatches Axios HTTP requests to REST endpoints (e.g., /api/auth, /api/links, /api/share).
- On login/signup → credentialsPOST → API verifies, issues JWT → React stores token in localStorage.
- Authenticated requests include Authorization header → Express middleware validates JWT → passes to route handlers.
- Route handlers perform CRUD on MongoDB via db.ts (using Mongoose or native driver).
- Sharing feature: generates a unique share-token/slug → stored in Mongo → public route serves read-only data.
c. Architectural patterns & design principles
- Separation of concerns: UI vs. business logic vs. data layer.
- RESTful API design.
- Single-page application (SPA) pattern on the frontend.
- Middle-tier authentication middleware in backend.
- Environment-based configuration (dotenv files).
d. Key technologies & libraries
- Frontend: React, TypeScript, Vite, Tailwind CSS, Axios, localStorage.
- Backend: Node.js, Express, TypeScript, MongoDB, JSON Web Token (jsonwebtoken), dotenv.
- Deployment: Vercel (frontend), any Node host or container (backend).

##### Detail
- Middleware layers (authentication, error handling).
- Development vs. production flows if relevant (Vite dev server vs. Vercel CDN, local Mongo vs. Atlas cluster).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Client Browser (React SPA)"]:::frontend
        StaticServer["Static Asset Server / CDN"]:::frontend
        Browser -->|"Fetch SPA Bundle"| StaticServer
        click Browser "https://github.com/vanshrana-1004/second-brain/tree/main/Frontend/src"
        click StaticServer "https://github.com/vanshrana-1004/second-brain/blob/main/Frontend/vite.config.ts"
        click StaticServer "https://github.com/vanshrana-1004/second-brain/blob/main/Frontend/vercel.json"
    end

    %% External Providers
    ExternalProviders["External Content Providers"]:::external
    classDef external stroke-dasharray: 5 5, stroke:#999

    ExternalProviders -.-> Browser

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        API["API Server (Express + Node.js)"]:::backend
        click API "https://github.com/vanshrana-1004/second-brain/blob/main/Backend/src/index.ts"

        subgraph "Configuration & Env"
            direction TB
            Env[".env & Config"]:::backend
            click Env "https://github.com/vanshrana-1004/second-brain/blob/main/.env.example"
            click Env "https://github.com/vanshrana-1004/second-brain/blob/main/Backend/src/config.ts"
        end

        subgraph "Utilities & Middleware"
            direction TB
            Util["Utility Functions"]:::backend
            click Util "https://github.com/vanshrana-1004/second-brain/blob/main/Backend/src/util.ts"
            AuthMiddleware["Authentication Middleware"]:::backend
            click AuthMiddleware "https://github.com/vanshrana-1004/second-brain/blob/main/Backend/src/middleware.ts"
        end

        subgraph "Route Handlers"
            direction TB
            AuthRoutes["Auth Routes (POST /api/auth)"]:::backend
            LinkRoutes["Link Mgmt Routes (CRUD /api/links)"]:::backend
            ShareRoutes["Share Service Routes (GET /api/share/:slug)"]:::backend
            click AuthRoutes "https://github.com/vanshrana-1004/second-brain/blob/main/Backend/src/index.ts"
            click LinkRoutes "https://github.com/vanshrana-1004/second-brain/blob/main/Backend/src/index.ts"
            click ShareRoutes "https://github.com/vanshrana-1004/second-brain/blob/main/Backend/src/index.ts"
        end

        API --> Env
        API --> Util
        API --> AuthMiddleware
        API --> AuthRoutes
        API --> LinkRoutes
        API --> ShareRoutes

        subgraph "Database"
            direction TB
            MongoDB[(MongoDB Cluster)]:::database
            click MongoDB "https://github.com/vanshrana-1004/second-brain/blob/main/Backend/src/db.ts"
        end

        Env --> MongoDB
        AuthRoutes --> MongoDB
        LinkRoutes --> MongoDB
        ShareRoutes --> MongoDB
    end

    %% Client-Server Interaction
    Browser -->|"POST /api/auth/login"| AuthRoutes
    Browser -->|"GET /api/links"| LinkRoutes
    Browser -->|"GET /api/share/:slug"| ShareRoutes
    AuthMiddleware -->|"Validates JWT"| AuthRoutes

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef backend fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef database fill:#fff8e1,stroke:#ff8f00,color:#bf360c
```
