# bhumesh01/secondbrain architecture

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

- Interactive diagram: https://gitdiagram.com/bhumesh01/secondbrain
- Repository: https://github.com/bhumesh01/secondbrain

## Overview

1. **Overall shape**
   - This is a split **MERN-style full-stack app** with a TypeScript **React/Vite frontend** in `client/` and an **Express/Node backend** in `server/`.
   - The frontend is a single-page app that talks to the backend over HTTP; the backend owns authentication, persistence, and content CRUD.

2. **Frontend presentation layer**
   - `client/src/main.tsx` boots the app, and `App.tsx` is the top-level composition point.
   - The UI is organized into reusable components under `src/components/ui/` such as sidebar, cards, buttons, and the content creation modal.
   - The presence of many icon components suggests the UI is centered around content-type tiles/actions rather than generic pages.

3. **Frontend routing and page boundaries**
   - `src/pages/` contains the main screens: `home`, `SignIn`, `SignUp`, `dashboard`, `ItemWise`, `anotherUserDashboard`, and `comingSoon`.
   - This indicates the app has distinct flows for onboarding/authentication, a user dashboard, per-item views, and a shared/public view for another user’s dashboard.

4. **Frontend state and API interaction**
   - `src/hooks/useContent.tsx` is the main custom hook for content-related state and actions.
   - That hook likely acts as the boundary between UI and backend API calls, handling fetch/create/delete/share flows and keeping the dashboard content synchronized.

5. **Content management UX**
   - `CreateContentModal` plus sidebar/sidebar-item components imply the main user workflow is: select a content type, create an entry, organize it, and navigate through categories/views.
   - The icon set includes link, tweet, YouTube, document, image, audio, and video symbols, so the app is designed to store heterogeneous “brain” items rather than one document type.

6. **Backend API layer**
   - `server/src/app.ts` is the Express application entry, with routing defined in `src/routes/routes.ts`.
   - The backend is separated into `authControllers.ts` and `crudControllers.ts`, which cleanly splits authentication from content operations.

7. **Backend security and request processing**
   - `src/middleware/middleware.ts` likely holds auth/verification middleware used to protect content routes.
   - The stack in the README confirms **JWT** for session/auth state and **bcrypt** for password hashing, so authenticated requests are a key architectural boundary.

8. **Persistence layer**
   - `src/config/db.ts` handles MongoDB connection setup, while `src/models/db.ts` defines the Mongoose model layer.
   - This means MongoDB is the system of record for users and saved content, with Mongoose providing the schema/data access boundary.

9. **Backend configuration and validation**
   - `src/config/hash.ts` centralizes password hashing logic.
   - The README mentions **Zod** input validation, so request payloads are validated before they reach persistence or business logic.

10. **Primary end-to-end data flow**
   - A user signs up/signs in from the frontend; credentials go to the auth endpoints; the backend hashes/verifies and returns a JWT.
   - The authenticated dashboard then uses the content API to load, create, and manage saved items; shared/public views are served through the `anotherUserDashboard` path or related backend endpoints.

11. **Deployment/runtime boundaries**
   - Both `client/vercel.json` and `server/vercel.json` indicate separate deployment targets for frontend and backend.
   - Environment variables are split by side: the client points to the backend URL, while the server needs MongoDB connection details and a JWT secret.

12. **What to emphasize in an architecture diagram**
   - Show two top-level zones: **React SPA** and **Express API**.
   - Inside the API, show auth, CRUD, middleware, and MongoDB/Mongoose.
   - Inside the client, show pages, reusable UI, custom content hook, and route-driven navigation.
   - The key integration points are **login/register**, **JWT-protected content operations**, and **shared dashboard/item views**.

Main entry points: [`client/src/pages`](https://github.com/bhumesh01/secondbrain/tree/main/client/src/pages) (Pages), [`server/src/routes/routes.ts`](https://github.com/bhumesh01/secondbrain/blob/main/server/src/routes/routes.ts) (Routes), [`server/src/controllers/authControllers.ts`](https://github.com/bhumesh01/secondbrain/blob/main/server/src/controllers/authControllers.ts) (Auth), [`client/src/App.tsx`](https://github.com/bhumesh01/secondbrain/blob/main/client/src/App.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React SPA"]
  node_client_main(("App boot<br/>entrypoint<br/>[main.tsx]"))
  node_client_app["App shell<br/>composition<br/>[App.tsx]"]
  node_client_pages["Pages<br/>routes"]
  node_client_hook["Content hook<br/>state/api<br/>[useContent.tsx]"]
  node_client_ui["UI kit<br/>components"]
  node_client_icons["Icons<br/>assets"]
  node_client_home["Home<br/>page<br/>[home.tsx]"]
  node_client_signin["Sign in<br/>auth page<br/>[SignIn.tsx]"]
  node_client_signup["Sign up<br/>auth page<br/>[SignUp.tsx]"]
  node_client_dashboard["Dashboard<br/>page<br/>[dashboard.tsx]"]
  node_client_item["Item view<br/>page<br/>[ItemWise.tsx]"]
  node_client_shared["Shared dashboard<br/>page"]
end

subgraph group_server["Express API"]
  node_server_app(("API entry<br/>entrypoint<br/>[app.ts]"))
  node_server_routes["Routes<br/>http routing<br/>[routes.ts]"]
  node_server_auth["Auth<br/>controller<br/>[authControllers.ts]"]
  node_server_crud["Content CRUD<br/>controller<br/>[crudControllers.ts]"]
  node_server_mw["Middleware<br/>security<br/>[middleware.ts]"]
  node_server_db[("Mongo config<br/>[db.ts]")]
  node_server_hash["Hash config<br/>[hash.ts]"]
  node_server_model[("Data model<br/>mongoose model<br/>[db.ts]")]
end

node_client_main -->|"mounts"| node_client_app
node_client_app -->|"routes to"| node_client_pages
node_client_app -->|"composes"| node_client_ui
node_client_app -->|"uses"| node_client_hook
node_client_ui -->|"renders"| node_client_icons
node_client_pages -->|"includes"| node_client_home
node_client_pages -->|"includes"| node_client_signin
node_client_pages -->|"includes"| node_client_signup
node_client_pages -->|"includes"| node_client_dashboard
node_client_pages -->|"includes"| node_client_item
node_client_pages -->|"includes"| node_client_shared
node_client_hook -->|"HTTP API"| node_server_routes
node_server_app -->|"wires"| node_server_routes
node_server_routes -->|"auth endpoints"| node_server_auth
node_server_routes -->|"content endpoints"| node_server_crud
node_server_routes -->|"protects"| node_server_mw
node_server_auth -->|"hashes"| node_server_hash
node_server_auth -->|"reads/writes"| node_server_model
node_server_crud -->|"reads/writes"| node_server_model
node_server_model -->|"connects via"| node_server_db
node_server_mw -.->|"verifies"| node_server_model
node_client_shared -->|"fetches shared data"| node_server_crud
node_client_dashboard -->|"manages content"| node_server_crud
node_client_signin -->|"submits credentials"| node_server_auth
node_client_signup -->|"submits signup"| node_server_auth

click node_client_main "https://github.com/bhumesh01/secondbrain/blob/main/client/src/main.tsx"
click node_client_app "https://github.com/bhumesh01/secondbrain/blob/main/client/src/App.tsx"
click node_client_pages "https://github.com/bhumesh01/secondbrain/tree/main/client/src/pages"
click node_client_hook "https://github.com/bhumesh01/secondbrain/blob/main/client/src/hooks/useContent.tsx"
click node_client_ui "https://github.com/bhumesh01/secondbrain/tree/main/client/src/components/ui"
click node_client_icons "https://github.com/bhumesh01/secondbrain/tree/main/client/src/icons"
click node_client_home "https://github.com/bhumesh01/secondbrain/blob/main/client/src/pages/home.tsx"
click node_client_signin "https://github.com/bhumesh01/secondbrain/blob/main/client/src/pages/SignIn.tsx"
click node_client_signup "https://github.com/bhumesh01/secondbrain/blob/main/client/src/pages/SignUp.tsx"
click node_client_dashboard "https://github.com/bhumesh01/secondbrain/blob/main/client/src/pages/dashboard.tsx"
click node_client_item "https://github.com/bhumesh01/secondbrain/blob/main/client/src/pages/ItemWise.tsx"
click node_client_shared "https://github.com/bhumesh01/secondbrain/blob/main/client/src/pages/anotherUserDashboard.tsx"
click node_server_app "https://github.com/bhumesh01/secondbrain/blob/main/server/src/app.ts"
click node_server_routes "https://github.com/bhumesh01/secondbrain/blob/main/server/src/routes/routes.ts"
click node_server_auth "https://github.com/bhumesh01/secondbrain/blob/main/server/src/controllers/authControllers.ts"
click node_server_crud "https://github.com/bhumesh01/secondbrain/blob/main/server/src/controllers/crudControllers.ts"
click node_server_mw "https://github.com/bhumesh01/secondbrain/blob/main/server/src/middleware/middleware.ts"
click node_server_db "https://github.com/bhumesh01/secondbrain/blob/main/server/src/config/db.ts"
click node_server_hash "https://github.com/bhumesh01/secondbrain/blob/main/server/src/config/hash.ts"
click node_server_model "https://github.com/bhumesh01/secondbrain/blob/main/server/src/models/db.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_main,node_client_app,node_client_pages,node_client_hook,node_client_ui,node_client_icons,node_client_home,node_client_signin,node_client_signup,node_client_dashboard,node_client_item,node_client_shared toneBlue
class node_server_app,node_server_routes,node_server_auth,node_server_crud,node_server_mw,node_server_db,node_server_hash,node_server_model toneAmber
```

## Components

### React SPA

Vite-powered frontend for onboarding, dashboards, and content management.

- [App boot](https://github.com/bhumesh01/secondbrain/blob/main/client/src/main.tsx): entrypoint · Starts the React application and mounts the root app. · `client/src/main.tsx`
- [App shell](https://github.com/bhumesh01/secondbrain/blob/main/client/src/App.tsx): composition · Top-level frontend composition and route orchestration. · `client/src/App.tsx`
- [Pages](https://github.com/bhumesh01/secondbrain/tree/main/client/src/pages): routes · Main screens for home, auth, dashboards, item views, and placeholder content. · `client/src/pages`
- [Content hook](https://github.com/bhumesh01/secondbrain/blob/main/client/src/hooks/useContent.tsx): state/api · Shared content state and API actions boundary for the UI. · `client/src/hooks/useContent.tsx`
- [UI kit](https://github.com/bhumesh01/secondbrain/tree/main/client/src/components/ui): components · Reusable presentation components for navigation, cards, buttons, and creation modal. · `client/src/components/ui`
- [Icons](https://github.com/bhumesh01/secondbrain/tree/main/client/src/icons): assets · Content-type and action icon set used throughout the interface. · `client/src/icons`
- [Home](https://github.com/bhumesh01/secondbrain/blob/main/client/src/pages/home.tsx): page · Public landing or entry screen. · `client/src/pages/home.tsx`
- [Sign in](https://github.com/bhumesh01/secondbrain/blob/main/client/src/pages/SignIn.tsx): auth page · Login flow for existing users. · `client/src/pages/SignIn.tsx`
- [Sign up](https://github.com/bhumesh01/secondbrain/blob/main/client/src/pages/SignUp.tsx): auth page · Registration flow for new users. · `client/src/pages/SignUp.tsx`
- [Dashboard](https://github.com/bhumesh01/secondbrain/blob/main/client/src/pages/dashboard.tsx): page · Primary authenticated workspace for managing saved items. · `client/src/pages/dashboard.tsx`
- [Item view](https://github.com/bhumesh01/secondbrain/blob/main/client/src/pages/ItemWise.tsx): page · Per-item or filtered content view for a selected category or item. · `client/src/pages/ItemWise.tsx`
- [Shared dashboard](https://github.com/bhumesh01/secondbrain/blob/main/client/src/pages/anotherUserDashboard.tsx): page · Another user's dashboard or public shared view. · `client/src/pages/anotherUserDashboard.tsx`

### Express API

Node/Express backend for auth, CRUD, validation, and persistence.

- [API entry](https://github.com/bhumesh01/secondbrain/blob/main/server/src/app.ts): entrypoint · Express application setup and middleware wiring. · `server/src/app.ts`
- [Routes](https://github.com/bhumesh01/secondbrain/blob/main/server/src/routes/routes.ts): http routing · Backend route table connecting endpoints to controllers. · `server/src/routes/routes.ts`
- [Auth](https://github.com/bhumesh01/secondbrain/blob/main/server/src/controllers/authControllers.ts): controller · Sign-in and sign-up handling with JWT-based session issuance. · `server/src/controllers/authControllers.ts`
- [Content CRUD](https://github.com/bhumesh01/secondbrain/blob/main/server/src/controllers/crudControllers.ts): controller · Create, read, update, delete, and share operations for stored items. · `server/src/controllers/crudControllers.ts`
- [Middleware](https://github.com/bhumesh01/secondbrain/blob/main/server/src/middleware/middleware.ts): security · Request protection and verification boundary for protected routes. · `server/src/middleware/middleware.ts`
- [Mongo config](https://github.com/bhumesh01/secondbrain/blob/main/server/src/config/db.ts): config · MongoDB connection setup. · `server/src/config/db.ts`
- [Hash config](https://github.com/bhumesh01/secondbrain/blob/main/server/src/config/hash.ts): config · Password hashing helper configuration. · `server/src/config/hash.ts`
- [Data model](https://github.com/bhumesh01/secondbrain/blob/main/server/src/models/db.ts): mongoose model · Mongoose schema and model definitions for users and saved content. · `server/src/models/db.ts`

## Connections

- App boot → App shell: mounts · Bootstraps the top-level React app.
- App shell → Pages: routes to · Selects the active page flow.
- App shell → UI kit: composes · Uses shared UI building blocks.
- App shell → Content hook: uses · Connects page state to backend actions.
- UI kit → Icons: renders · Uses icons for content types and actions.
- Pages → Home: includes · Public landing screen.
- Pages → Sign in: includes · Authentication screen.
- Pages → Sign up: includes · Registration screen.
- Pages → Dashboard: includes · Primary workspace.
- Pages → Item view: includes · Item/category-specific view.
- Pages → Shared dashboard: includes · Shared or other-user dashboard view.
- Content hook → Routes: HTTP API · Loads and mutates content through backend endpoints.
- API entry → Routes: wires · Registers backend routes.
- Routes → Auth: auth endpoints · Routes login and registration requests.
- Routes → Content CRUD: content endpoints · Routes content management requests.
- Routes → Middleware: protects · Applies verification to guarded routes.
- Auth → Hash config: hashes · Uses password hashing helpers.
- Auth → Data model: reads/writes · Persists and validates user records.
- Content CRUD → Data model: reads/writes · Persists saved content and metadata.
- Data model → Mongo config: connects via · Uses the MongoDB connection.
- Middleware → Data model: verifies · Supports authenticated request checks against stored data or tokens.
- Shared dashboard → Content CRUD: fetches shared data · Displays content shared from another user.
- Dashboard → Content CRUD: manages content · Creates and updates saved items.
- Sign in → Auth: submits credentials · Sends login requests.
- Sign up → Auth: submits signup · Sends registration requests.
