# jitashi-arora/signalist_stock-tracker-app architecture

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

- Interactive diagram: https://gitdiagram.com/jitashi-arora/signalist_stock-tracker-app
- Repository: https://github.com/jitashi-arora/signalist_stock-tracker-app

## Overview

##### Project type and purpose
- This is a full-stack Next.js application (using the new “app” router) that provides users with stock information, real‐time market data (via Finnhub), user authentication (sign-in/sign-up), and background tasks (via Inngest) such as email notifications (via nodemailer).
- It uses React server components, client components, Mongoose/MongoDB, and several service integrations.

##### File structure
- app/
- (root) pages: layout.tsx, page.tsx, dynamic stock pages under /stocks/[symbol]
- (auth) pages: sign-in, sign-up
- app/api/inngest/route.ts: Next.js API route for Inngest webhooks
- components/: reusable UI components (buttons, inputs, dialogs, TradingViewWidget, SearchCommand, UserDropdown)
- database/mongoose.ts: MongoDB connection setup
- lib/:
- actions/: business‐logic wrappers for auth and Finnhub calls
- better-auth/: custom auth utilities
- inngest/: client definitions and serverless function handlers
- nodemailer/: email‐templating utilities
- utils.ts, constants.ts
- middleware/index.ts: Next.js middleware for routing/auth checks
- hooks/: custom React hooks (debounce, TradingView widget state)
- config files: next.config.ts, tsconfig.json, eslint.config.mjs, postcss.config.mjs

##### README insights
- Standard Next.js app bootstrapped with create-next-app

##### Main components
a. Client (Browser)
- React pages/components hosted at app/
- Fetches data via Next.js data-fetching (server components) and client hooks
b. Next.js Server (App Router)
- Renders server and client components
- Exposes API route: /api/inngest → triggers Inngest functions
- Executes business-logic in lib/actions and lib/inngest/functions
- Hosts middleware for authentication/authorization
c. Database Layer
- MongoDB cluster accessed via Mongoose (database/mongoose.ts)
- Stores user profiles, saved watchlists, or application metadata
d. Background/Event Processing
- Inngest event orchestrator – receives HTTP events → runs serverless function handlers defined in lib/inngest/functions.ts
- Used for scheduled tasks or heavy background jobs (e.g. data enrichment, notifications)
e. External Services
- Finnhub REST API (lib/actions/finnhub.actions.ts) for real-time stock data
- SMTP/email provider (via lib/nodemailer) for account emails, alerts
f. Static Assets & Configuration
- next.config.ts and postcss.config.mjs for build/deployment

##### Relationships and interactions
- Browser → Next.js Server: page navigations, form submissions, client‐component fetches
- Next.js Server → MongoDB: CRUD via Mongoose
- Next.js Server → Finnhub API: data fetch
- Next.js Server → SMTP server: send emails via nodemailer
- Next.js Server → Inngest: enqueue or trigger events via the Inngest client
- Inngest (worker) → Next.js Server (API route) or direct function execution → may read/write DB, call external APIs

##### Architectural patterns & principles
- Layered architecture: Presentation (app/ + components/), Business Logic (lib/actions, lib/utils), Data Access (database/, Mongoose models)
- Serverless/API‐route driven background processing with Inngest
- Separation of concerns: distinct folders for hooks, UI, API, services
- File-based routing for pages and API endpoints
- Use of React server components for SSR/SSG and client components for interactivity

##### Essential elements
- Clear labels on all components and services

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Layer
    subgraph "Browser" 
        direction TB
        UI_Pages["Client UI Pages"]:::ui
        Auth_Pages["Authentication Pages"]:::ui
        UI_Components["Reusable UI Components"]:::ui
    end

    %% Next.js Server Layer
    subgraph "Next.js App"
        direction TB
        Middleware["Next.js Middleware<br/>(Auth/Router Checks)"]:::srv
        API_Inngest["API Route<br/>(/api/inngest)"]:::srv
        Auth_Actions["Auth Actions<br/>(lib/actions/auth.actions.ts)"]:::srv
        Finnhub_Actions["Finnhub Actions<br/>(lib/actions/finnhub.actions.ts)"]:::srv
        Better_Auth["Better Auth Utilities"]:::srv
        Email_Utils["Email Utilities<br/>(Nodemailer)"]:::srv
        Utils_Consts["Utility Functions & Constants"]:::srv
        Mongo_Conn["MongoDB Connection"]:::srv
        Configs["Next.js Configuration"]:::srv
    end

    %% Inngest Worker Layer
    subgraph "Inngest Worker"
        direction TB
        Inngest_Client["Inngest Client"]:::bg
        Inngest_Functions["Inngest Functions"]:::bg
    end

    %% Database
    MongoDB["MongoDB Cluster"]:::db

    %% External Services
    Finnhub["Finnhub API"]:::ext
    SMTP["SMTP/Email Provider"]:::ext

    %% Static Assets
    Assets["Static Assets<br/>(public/assets)"]:::ext

    %% Connections
    UI_Pages -->|"GET /, /stocks/[symbol]"| API_Inngest
    UI_Pages -->|"SSR/SSG fetch"| Auth_Actions
    Auth_Pages -->|"POST /sign-in, /sign-up"| Auth_Actions
    UI_Components --> UI_Pages

    UI_Pages -->|"Client Hooks"| Utils_Consts

    API_Inngest -->|"webhook event"| Inngest_Functions
    Middleware -->|Intercepts| API_Inngest
    Auth_Actions -->|"read/write"| Mongo_Conn
    Finnhub_Actions -->|"REST API call"| Finnhub
    Email_Utils -->|"SMTP send"| SMTP
    Utils_Consts --> API_Inngest

    API_Inngest -->|"enqueueNotification"| Inngest_Client
    Inngest_Client -->|"invoke"| Inngest_Functions
    Inngest_Functions -->|"DB operations"| Mongo_Conn
    Inngest_Functions -->|"call external"| Finnhub
    Inngest_Functions -->|"sendMail"| Email_Utils

    Mongo_Conn -->|connect| MongoDB

    UI_Pages -->|"static files"| Assets

    %% Click Events
    click UI_Pages "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/app/(root)/layout.tsx"
    click UI_Pages "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/app/(root)/page.tsx"
    click UI_Pages "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/app/(root)/stocks/[symbol]/page.tsx"
    click Auth_Pages "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/app/(auth)/sign-in/page.tsx"
    click Auth_Pages "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/app/(auth)/sign-up/page.tsx"
    click Auth_Pages "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/app/(auth)/layout.tsx"
    click UI_Components "https://github.com/jitashi-arora/signalist_stock-tracker-app/tree/main/components/"
    click API_Inngest "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/app/api/inngest/route.ts"
    click Middleware "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/middleware/index.ts"
    click Auth_Actions "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/lib/actions/auth.actions.ts"
    click Finnhub_Actions "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/lib/actions/finnhub.actions.ts"
    click Better_Auth "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/lib/better-auth/auth.ts"
    click Inngest_Client "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/lib/inngest/client.ts"
    click Inngest_Functions "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/lib/inngest/functions.ts"
    click Email_Utils "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/lib/nodemailer/index.ts"
    click Email_Utils "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/lib/nodemailer/templates.ts"
    click Utils_Consts "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/lib/utils.ts"
    click Utils_Consts "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/lib/constants.ts"
    click Mongo_Conn "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/database/mongoose.ts"
    click Assets "https://github.com/jitashi-arora/signalist_stock-tracker-app/tree/main/public/assets/icons"
    click Assets "https://github.com/jitashi-arora/signalist_stock-tracker-app/tree/main/public/assets/images"
    click Configs "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/next.config.ts"
    click Configs "https://github.com/jitashi-arora/signalist_stock-tracker-app/blob/main/postcss.config.mjs"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef srv fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef db fill:#d4edda,stroke:#333,stroke-width:1px
    classDef ext fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef bg fill:#ffe5b4,stroke:#333,stroke-width:1px
```
