# abhinab-choudhury/shortwave architecture

> Architecture diagram of the GitHub repository abhinab-choudhury/shortwave, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhinab-choudhury/shortwave
- Repository: https://github.com/abhinab-choudhury/shortwave

## Overview

##### Project type and purpose
- This is a full-stack URL-shortening and analytics dashboard called ShortWave.
- Frontend: React (Vite) SPA providing a dashboard (links, click stats, QR codes, settings, auth) using Tailwind + shadcn UI.
- Backend: Node.js/TypeScript Express app exposing REST endpoints (shorten, redirect, analytics, user management) with layered controllers→services→models, OAuth (Passport.js), rate limiting, error handling.
- Data stores: MongoDB (Prisma or Mongoose schemas in apps/server/src/database/models) and Redis (for caching, JWT blacklisting or rate-limiting).
- External integrations: OAuth providers (Google, GitHub, Facebook), Firebase Messaging, Stripe payments, e-mail service.

##### File structure
- Top-level “apps”:
- apps/client → React SPA with src/pages, src/components (layout & UI libs), src/hooks & providers for theme, auth, sidebar.
- apps/server → Express API:
– routes → user, auth, url, campaign, redirect, etc.
– controllers → one per domain, thin layer for request/response.
– services → business logic, called by controllers.
– database → db-connect, Prisma/Mongoose models, redis-connect.
– middlewares → auth checks, rate-limiter, error handler.
– strategies → Passport OAuth strategies.
– utils → error/response helpers, email, UA parsing, secrets.
– views → ejs templates (for server-side render if any).
- docker-compose.yml brings up client, server, MongoDB, Redis; each app has Dockerfile & .env.example.

##### README for additional insights
- Confirms stack details (React, Prisma/MongoDB, Passport OAuth, Tailwind, shadcn UI, Firebase Messaging, Stripe).
- Outlines feature ideas: custom link pages, QR code generation, detailed analytics (CTR, device breakdown, geo, engagement).
- Emphasizes SaaS-style dashboard, light/dark theme, cookie banner, AI features.

##### Detail without overthinking
- Decompose the backend into internal layers (controllers vs. services vs. models) only if the audience needs that depth. Otherwise group them into one “Backend API Service” node.
- Every piece that’s critical to your use cases: short-URL generation, QR code, auth flow, analytics tracking, notification dispatch.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (React Vite SPA)"
        direction TB
        FE_SPA["Client SPA"]:::frontend
        FE_Entry["Entry Point\n(main.tsx)"]:::frontend
        FE_Root["Root Component\n(App.tsx)"]:::frontend
        FE_Pages["Pages\n(src/pages)"]:::frontend
        FE_UI["UI Components\n(src/components/ui)"]:::frontend
        FE_Features["Feature Components\n(src/components)"]:::frontend
        FE_Providers["Providers\n(src/providers)"]:::frontend
        FE_Hooks["Custom Hooks\n(src/hooks)"]:::frontend
        FE_SPA --> FE_Entry
        FE_Entry --> FE_Root
        FE_Root --> FE_Pages
        FE_Root --> FE_UI
        FE_Root --> FE_Features
        FE_Root --> FE_Providers
        FE_Root --> FE_Hooks
    end

    %% Backend Layer
    subgraph "Backend API Service (Express)"
        direction TB
        BE_Entry["API Entry Point\n(index.ts)"]:::backend
        BE_Routes["Routes\n(src/routes)"]:::backend
        BE_Controllers["Controllers\n(src/controllers)"]:::backend
        BE_Services["Services\n(src/services)"]:::backend
        BE_DBConnect["DB Connect\n(db-connect.ts)"]:::backend
        BE_RedisConnect["Redis Connect\n(redis-connect.ts)"]:::backend
        BE_Models["Data Models\n(src/database/models)"]:::backend
        BE_Middlewares["Middlewares\n(src/middlewares)"]:::backend
        BE_Strategies["OAuth Strategies\n(src/strategies)"]:::backend
        BE_Utils["Utils\n(src/utils)"]:::backend
        BE_Views["Views\n(src/views/index.ejs)"]:::backend

        BE_Entry --> BE_Routes
        BE_Routes --> BE_Controllers
        BE_Controllers --> BE_Services
        BE_Services --> BE_Models
        BE_DBConnect --> BE_Models
        BE_RedisConnect --> BE_Middlewares
        BE_Middlewares --> BE_Routes
        BE_Strategies --> BE_Middlewares
        BE_Utils --> BE_Services
        BE_Views --> BE_Controllers
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        MongoDB["MongoDB"]:::datastore
        Redis["Redis"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OAuth["OAuth Providers\n(Google, GitHub, Facebook)"]:::external
        Firebase["Firebase Messaging"]:::external
        Stripe["Stripe Payments"]:::external
        EmailSvc["Email Service (SMTP)"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        DockerCompose["docker-compose.yml"]:::infra
        DockerClient["Client Dockerfile"]:::infra
        DockerServer["Server Dockerfile"]:::infra
    end

    %% Interactions
    Browser["Browser"]:::external
    Browser -->|"HTTPS"| FE_SPA
    FE_SPA -->|"API Calls (JSON)"| BE_Entry
    BE_Entry --> BE_Middlewares
    BE_Middlewares -->|"Rate Limit, Auth"| BE_Routes
    BE_Routes --> BE_Controllers
    BE_Controllers --> BE_Services
    BE_Services -->|Reads/Writes| MongoDB
    BE_Middlewares -->|Cache Check| Redis
    BE_Services -->|Blacklisting Tokens| Redis
    BE_Middlewares --> BE_Strategies
    BE_Strategies -->|OAuth Flow| OAuth
    BE_Services -->|Send Notifications| Firebase
    BE_Services -->|Process Payments| Stripe
    BE_Utils -->|Send Emails| EmailSvc
    BE_Entry --> DockerCompose
    FE_SPA --> DockerCompose
    MongoDB --> DockerCompose
    Redis --> DockerCompose
    DockerClient --> DockerCompose
    DockerServer --> DockerCompose

    %% Click Events
    click FE_SPA "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/client"
    click FE_Entry "https://github.com/abhinab-choudhury/shortwave/blob/main/apps/client/src/main.tsx"
    click FE_Root "https://github.com/abhinab-choudhury/shortwave/blob/main/apps/client/src/App.tsx"
    click FE_Pages "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/client/src/pages"
    click FE_UI "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/client/src/components/ui"
    click FE_Features "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/client/src/components"
    click FE_Providers "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/client/src/providers"
    click FE_Hooks "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/client/src/hooks"
    click BE_Entry "https://github.com/abhinab-choudhury/shortwave/blob/main/apps/server/src/index.ts"
    click BE_Routes "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/server/src/routes"
    click BE_Controllers "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/server/src/controllers"
    click BE_Services "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/server/src/services"
    click BE_DBConnect "https://github.com/abhinab-choudhury/shortwave/blob/main/apps/server/src/database/db-connect.ts"
    click BE_RedisConnect "https://github.com/abhinab-choudhury/shortwave/blob/main/apps/server/src/database/redis-connect.ts"
    click BE_Models "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/server/src/database/models"
    click BE_Middlewares "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/server/src/middlewares"
    click BE_Strategies "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/server/src/strategies"
    click BE_Utils "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/server/src/utils"
    click BE_Views "https://github.com/abhinab-choudhury/shortwave/blob/main/apps/server/src/views/index.ejs"
    click DockerCompose "https://github.com/abhinab-choudhury/shortwave/blob/main/docker-compose.yml"
    click DockerClient "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/client/Dockerfile"
    click DockerServer "https://github.com/abhinab-choudhury/shortwave/tree/main/apps/server/Dockerfile"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#007ACC,color:#000
    classDef backend fill:#DFF7DF,stroke:#28A745,color:#000
    classDef datastore fill:#FFE8A1,stroke:#FFB700,color:#000
    classDef external fill:#F3DFFF,stroke:#9C27B0,color:#000
    classDef infra fill:#ECECEC,stroke:#6C757D,color:#000
```
