# jitashi-arora/stockify architecture

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

- Interactive diagram: https://gitdiagram.com/jitashi-arora/stockify
- Repository: https://github.com/jitashi-arora/stockify

## Overview

##### Project type & purpose (what you’re diagramming)
This is a **Next.js (App Router) full-stack web application**. The file tree indicates:
- **UI + routing** in `app/` using route groups `(auth)` and `(root)`.
- **Authentication** implemented via `lib/better-auth/*` and `lib/actions/auth.actions.ts`.
- **Database access** via **Mongoose/MongoDB** in `database/mongoose.ts`.
- **Market data** integration via `lib/actions/finnhub.actions.ts` (Finnhub API).
- **Background/workflow jobs** using **Inngest**: `app/api/inngest/route.ts`, `lib/inngest/*`.
- **Email delivery** via **Nodemailer**: `lib/nodemailer/*`.
- **Client-facing stock views/widgets**: `components/TradingViewWidget.tsx`, stock routes under `app/(root)/stocks/[symbol]/page.tsx`.

So the “system design” should show: **browser → Next.js app (SSR/RSC + API routes + server actions) → DB + external services (Auth, Finnhub, Inngest, Email, TradingView)**.

##### Page renders UI components; client components may call external embeds (TradingView)

- “HTTPS GET /stocks/:symbol”
- “Server Action: fetchQuote(symbol)”
- “Mongo query: findUserById”
- “REST: Finnhub quote endpoint”

##### Auth flows (must be a clear mini-subdiagram)
- **Browser** → **(auth)/sign-in page**
- Sign-in form → **Auth server action** → **Better Auth** → **DB** (user lookup)
- Better Auth → **Session/Cookie issued** → Browser
- **Middleware** checks cookie/session → allows/denies access to `(root)` routes

##### Inngest flows (event-driven path)
- **Inngest Cloud** → **Next.js API route `/api/inngest`** (webhook/handler)
- Handler → **Inngest Functions** → side effects:
- DB writes (MongoDB)
- External calls (Finnhub)
- Email sends (Nodemailer → SMTP)

##### TradingView integration
- Stock detail page → `TradingViewWidget.tsx`
- Widget → **TradingView (external embed)** directly from the client (browser → TradingView)

This should be drawn because it’s a distinct dependency that bypasses your server.

##### Architectural patterns to reflect
- **Next.js App Router** separation: route groups `(auth)` vs `(root)`.
- **Server Actions / service layer** pattern under `lib/actions/*`.
- **Middleware-based access control** (auth gating at the edge).
- **Integration-heavy architecture**: DB + Finnhub + Inngest + SMTP + TradingView embed.
- **Event-driven background processing** via Inngest (async tasks separate from user requests).

##### Don’t overthink it: split into *many* components (what “detailed” means here)
- `(auth)` vs `(root)` route groups
- middleware
- server actions (auth vs finnhub)
- database connector + database
- inngest route handler vs inngest functions vs inngest cloud
- nodemailer service vs smtp provider
- tradingview widget vs tradingview external

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% External Actors/Services
  %% =========================
  User["User Browser"]:::external

  Mongo[("MongoDB")]:::db
  Finnhub["Finnhub API"]:::external
  InngestCloud["Inngest Cloud"]:::external
  SMTP["SMTP / Email Provider"]:::external
  TradingView["TradingView Embed Service"]:::external

  %% =========================
  %% Next.js Application Boundary
  %% =========================
  subgraph "Stock Web App (Next.js App Router)"
    direction TB

    AppShell["Next.js App Shell\n(app/layout.tsx + globals)"]:::next

    subgraph "Edge Runtime"
      direction TB
      Middleware["Next.js Middleware\nRoute gating/auth checks"]:::security
    end

    subgraph "Presentation Layer (App Router UI)"
      direction TB

      subgraph "Route Group: (auth)"
        direction TB
        AuthGroup["Auth Pages + Layout\n(sign-in / sign-up)"]:::next
        SignIn["Sign-in Page"]:::next
        SignUp["Sign-up Page"]:::next
      end

      subgraph "Route Group: (root)"
        direction TB
        RootGroup["Main App Pages + Layout\n(home + stocks)"]:::next
        Home["Home Page"]:::next
        StockDetail["Stock Detail Route\n/stocks/:symbol"]:::next
      end

      subgraph "Shared Client UI"
        direction TB
        UIComponents["Shared UI Components"]:::ui
        UIlib["UI Component Library (ui/*)"]:::ui
        Forms["Form Components (forms/*)"]:::ui

        SearchCmd["Search / Command Palette"]:::ui
        UserDropdown["User Dropdown"]:::ui
        TVWidget["TradingView Widget (client embed)"]:::ui

        Hooks["Client Hooks / UX Helpers\n(debounce + widget hook)"]:::ui
      end
    end

    subgraph "Server Layer (Actions/Services + Integrations)"
      direction TB

      Utils["Shared Utilities & Constants"]:::svc

      AuthActions["Auth Service (Server Actions)"]:::svc
      BetterAuth["Auth Provider (Better Auth)"]:::security

      FinnhubActions["Market Data Service (Finnhub Actions)"]:::svc

      Mongoose["Database Connector / ODM (Mongoose)"]:::data

      subgraph "Background Workflows (Inngest)"
        direction TB
        InngestRoute["Inngest API Route Handler\n/api/inngest"]:::api
        InngestFns["Inngest Functions + Prompts"]:::svc
      end

      EmailSvc["Email Service (Nodemailer + Templates)"]:::svc
    end
  end

  %% =========================
  %% Core request/response flows
  %% =========================
  User -->|"HTTPS:page_requests"| AppShell
  AppShell -->|"applies_layouts+RSC/SSR"| AuthGroup
  AppShell -->|"applies_layouts+RSC/SSR"| RootGroup

  %% Middleware gating
  User -->|"navigate_(root)_routes"| Middleware
  Middleware -->|"allow/deny_based_on_session"| RootGroup

  %% Auth flows
  AuthGroup -->|"render"| SignIn
  AuthGroup -->|"render"| SignUp
  SignIn -->|"submit_credentials"| AuthActions
  SignUp -->|"submit_registration"| AuthActions
  AuthActions -->|"authenticate/issue_session"| BetterAuth
  BetterAuth -->|"user_lookup/verify"| Mongoose
  Mongoose -->|"Mongo_queries"| Mongo
  BetterAuth -->|"set_session_cookie"| User
  Middleware -->|"read_session_cookie"| BetterAuth

  %% Stocks / market data flows
  RootGroup -->|"render"| Home
  RootGroup -->|"render"| StockDetail
  StockDetail -->|"Server_Action:fetchQuote(symbol)"| FinnhubActions
  FinnhubActions -->|"REST:quote/profile"| Finnhub

  %% DB usage from server layer (general)
  AuthActions -->|"read/write_user"| Mongoose
  FinnhubActions -->|"optional_cache/persist"| Mongoose

  %% Shared UI usage
  RootGroup -->|"uses"| UIComponents
  AuthGroup -->|"uses"| UIComponents
  UIComponents -->|"uses"| UIlib
  AuthGroup -->|"uses"| Forms
  UIComponents -->|"includes"| SearchCmd
  UIComponents -->|"includes"| UserDropdown
  StockDetail -->|"includes"| TVWidget
  TVWidget -->|"uses"| Hooks

  %% TradingView bypass (client -> external)
  User -->|"loads_embed_assets"| TradingView

  %% =========================
  %% Inngest (event-driven) flows
  %% =========================
  InngestCloud -.->|"event_webhook"| InngestRoute
  InngestRoute -.->|"dispatch_jobs"| InngestFns
  InngestFns -.->|"DB_writes/reads"| Mongoose
  InngestFns -.->|"REST:market_data"| Finnhub
  InngestFns -.->|"send_email"| EmailSvc
  EmailSvc -.->|"SMTP_send"| SMTP

  %% =========================
  %% Click Events (component mapping)
  %% =========================
  click AppShell "https://github.com/jitashi-arora/stockify/blob/main/app/layout.tsx"
  click AppShell "https://github.com/jitashi-arora/stockify/blob/main/app/globals.css"

  click AuthGroup "https://github.com/jitashi-arora/stockify/blob/main/app/(auth)/layout.tsx"
  click SignIn "https://github.com/jitashi-arora/stockify/blob/main/app/(auth)/sign-in/page.tsx"
  click SignUp "https://github.com/jitashi-arora/stockify/blob/main/app/(auth)/sign-up/page.tsx"

  click RootGroup "https://github.com/jitashi-arora/stockify/blob/main/app/(root)/layout.tsx"
  click Home "https://github.com/jitashi-arora/stockify/blob/main/app/(root)/page.tsx"
  click StockDetail "https://github.com/jitashi-arora/stockify/blob/main/app/(root)/stocks/[symbol]/page.tsx"

  click UIComponents "https://github.com/jitashi-arora/stockify/tree/main/components/"
  click SearchCmd "https://github.com/jitashi-arora/stockify/blob/main/components/SearchCommand.tsx"
  click TVWidget "https://github.com/jitashi-arora/stockify/blob/main/components/TradingViewWidget.tsx"
  click UserDropdown "https://github.com/jitashi-arora/stockify/blob/main/components/UserDropdown.tsx"
  click UIlib "https://github.com/jitashi-arora/stockify/tree/main/components/ui/"
  click Forms "https://github.com/jitashi-arora/stockify/tree/main/components/forms/"

  click Hooks "https://github.com/jitashi-arora/stockify/blob/main/hooks/useDebounce.ts"
  click Hooks "https://github.com/jitashi-arora/stockify/blob/main/hooks/userTradingViewWidget.tsx"

  click AuthActions "https://github.com/jitashi-arora/stockify/blob/main/lib/actions/auth.actions.ts"
  click FinnhubActions "https://github.com/jitashi-arora/stockify/blob/main/lib/actions/finnhub.actions.ts"
  click Utils "https://github.com/jitashi-arora/stockify/blob/main/lib/utils.ts"
  click Utils "https://github.com/jitashi-arora/stockify/blob/main/lib/constants.ts"

  click BetterAuth "https://github.com/jitashi-arora/stockify/blob/main/lib/better-auth/auth.ts"

  click Mongoose "https://github.com/jitashi-arora/stockify/blob/main/database/mongoose.ts"

  click InngestRoute "https://github.com/jitashi-arora/stockify/blob/main/app/api/inngest/route.ts"
  click InngestFns "https://github.com/jitashi-arora/stockify/blob/main/lib/inngest/client.ts"
  click InngestFns "https://github.com/jitashi-arora/stockify/blob/main/lib/inngest/functions.ts"
  click InngestFns "https://github.com/jitashi-arora/stockify/blob/main/lib/inngest/prompts.ts"

  click EmailSvc "https://github.com/jitashi-arora/stockify/blob/main/lib/nodemailer/index.ts"
  click EmailSvc "https://github.com/jitashi-arora/stockify/blob/main/lib/nodemailer/templates.ts"

  click Middleware "https://github.com/jitashi-arora/stockify/blob/main/middleware/index.ts"

  %% =========================
  %% Styles
  %% =========================
  classDef next fill:#2563eb,stroke:#0b3aa4,color:#ffffff,stroke-width:1px
  classDef api fill:#1d4ed8,stroke:#0b3aa4,color:#ffffff,stroke-width:1px
  classDef svc fill:#1e40af,stroke:#0b3aa4,color:#ffffff,stroke-width:1px
  classDef ui fill:#60a5fa,stroke:#1d4ed8,color:#0b1b3a,stroke-width:1px
  classDef security fill:#16a34a,stroke:#065f46,color:#ffffff,stroke-width:1px
  classDef data fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:1px
  classDef db fill:#6b7280,stroke:#111827,color:#ffffff,stroke-width:1px
  classDef external fill:#fb923c,stroke:#9a3412,color:#111827,stroke-width:1px
```
