# mrinmoypatratint/social-marketing-saas architecture

> Architecture diagram of the GitHub repository mrinmoypatratint/social-marketing-saas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mrinmoypatratint/social-marketing-saas
- Repository: https://github.com/mrinmoypatratint/social-marketing-saas

## Overview

#### 1. Purpose and runtime shape
SocialGen is a multi-tenant SaaS for AI content generation, brand-voice customization, campaign scheduling, social publishing, and engagement dashboards. It runs as a React/Vite SPA plus a Node.js/Express API, with native SQLite as the primary local relational store and optional Firebase integration.

Entry points:
- Backend process: `backend/src/server.js`, assembled in `backend/src/app.js`
- Frontend SPA: `frontend/src/main.jsx`, routed/application shell in `frontend/src/App.jsx`

#### 2. Client application and access boundary
The React client exposes product workflows as page-level views: dashboard, calendar, AI/blog generation, content remixing, hashtags, brand voice, social accounts/inbox, and settings. Shared layout and client-side route protection frame authenticated screens.

Key paths:
- `frontend/src/App.jsx`
- `frontend/src/context/AuthContext.jsx`
- `frontend/src/components/auth/ProtectedRoute.jsx`

The client calls the backend through its API service layer; auth and broader UI state are held in React contexts. Firebase client configuration exists separately, likely for optional cloud services rather than replacing the API’s primary SQLite path.

Key paths:
- `frontend/src/services/api.js`
- `frontend/src/context/GlobalStateContext.jsx`
- `frontend/src/firebase.js`

#### 3. API composition and security
Express composes domain routers for authentication, AI jobs, campaign calendar, dashboard metrics, and social integrations. JWT middleware establishes the authenticated-user boundary for protected operations; routes should scope records and credentials to that user.

Key paths:
- `backend/src/app.js`
- `backend/src/middleware/auth.js`
- `backend/src/routes/auth.js`

Primary API domains:
- `backend/src/routes/ai.js`
- `backend/src/routes/calendar.js`
- `backend/src/routes/dashboard.js`
- `backend/src/routes/social.js`

#### 4. Persistence and tenant data
SQLite is the stated primary system of record, accessed through a native synchronous `node:sqlite` connection and centralized query module. It persists users/settings, generated content jobs, scheduling records, social/account state, and data needed for dashboard aggregation. Firebase Admin support provides an optional cloud/document integration path.

Key paths:
- `backend/src/db/connection.js`
- `backend/src/db/queries.js`
- `backend/src/db/firebase.js`

Firestore and Storage policy/index files indicate Firebase infrastructure is provisioned alongside the local database model:
- `firestore.rules`
- `firestore.indexes.json`
- `storage.rules`

#### 5. AI content-generation flow
An authenticated client creates or manages AI jobs through the AI router. The backend combines request parameters with persisted user brand-voice settings, invokes Gemini, records status/results, and lets users retrieve, edit, delete, or retry historical jobs. Generated content feeds blog and social-content UI workflows.

Key paths:
- `backend/src/routes/ai.js`
- `backend/src/services/gemini.js`
- `frontend/src/pages/BlogGenerator.jsx`

External dependency: Google Gemini 2.5 Flash via `GEMINI_API_KEY`.

#### 6. Campaign lifecycle and analytics
Calendar APIs create, read, update, and delete campaign schedule entries. Scheduling/publishing services bridge planned content to social delivery, while dashboard endpoints aggregate campaign and engagement/sentiment metrics for the UI.

Key paths:
- `backend/src/routes/calendar.js`
- `backend/src/services/scheduler.js`
- `backend/src/routes/dashboard.js`

Corresponding UI surfaces:
- `frontend/src/pages/Calendar.jsx`
- `frontend/src/pages/Dashboard.jsx`

#### 7. Social OAuth and publishing boundary
Social account connection and publishing are isolated behind social routes and services. OAuth credentials/tokens for LinkedIn, Twitter/X, and Meta are external-service concerns; publisher adapters execute platform-specific posting while the application retains user-scoped account and schedule state.

Key paths:
- `backend/src/routes/social.js`
- `backend/src/services/socialAuth.js`
- `backend/src/services/socialPublishers.js`

Required optional infrastructure is configured by provider client IDs/secrets documented in `backend/.env.example` and `APIS_SETUP.md`.

Main entry points: [`backend/src/app.js`](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/app.js) (Express app), [`backend/src/db/queries.js`](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/db/queries.js) (SQLite query layer), [`backend/src/routes/social.js`](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/routes/social.js) (Social routes), [`frontend/src/App.jsx`](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/App.jsx) (Product workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React SPA"]
  node_spa_entry["SPA entry &amp; shell<br/>React/Vite<br/>[main.jsx]"]
  node_auth_ui["Auth context &amp; guards<br/>client auth<br/>[AuthContext.jsx]"]
  node_product_pages["Product workflows<br/>React pages<br/>[App.jsx]"]
  node_api_client["API service layer<br/>HTTP client<br/>[api.js]"]
  node_global_state["Global UI state<br/>React context"]
  node_firebase_client["Firebase client<br/>optional cloud client<br/>[firebase.js]"]
end

subgraph group_api["Express API"]
  node_server["Backend process<br/>Node.js entry<br/>[server.js]"]
  node_express_app["Express app<br/>API composition<br/>[app.js]"]
  node_jwt_auth["JWT auth middleware<br/>security boundary<br/>[auth.js]"]
  node_auth_routes["Auth routes<br/>router<br/>[auth.js]"]
  node_ai_routes["AI job routes<br/>router<br/>[ai.js]"]
  node_calendar_routes["Calendar routes<br/>router<br/>[calendar.js]"]
  node_dashboard_routes["Dashboard routes<br/>router<br/>[dashboard.js]"]
  node_social_routes["Social routes<br/>router<br/>[social.js]"]
end

subgraph group_data["Data &amp; integrations"]
  node_sqlite_queries["SQLite query layer<br/>tenant data access<br/>[queries.js]"]
  node_sqlite[("SQLite database<br/>primary system of record<br/>[connection.js]")]
  node_gemini{{"Gemini service<br/>AI integration<br/>[gemini.js]"}}
  node_scheduler["Scheduler<br/>campaign delivery<br/>[scheduler.js]"]
  node_social_auth["Social OAuth service<br/>OAuth integration<br/>[socialAuth.js]"]
  node_social_publishers["Social publisher adapters<br/>platform delivery"]
  node_firebase_admin["Firebase Admin<br/>optional cloud integration<br/>[firebase.js]"]
end

node_spa_entry --> node_auth_ui
node_spa_entry -->|"renders routes"| node_product_pages
node_auth_ui -->|"protects"| node_product_pages
node_product_pages -->|"uses"| node_global_state
node_product_pages -->|"calls"| node_api_client
node_api_client -->|"HTTP API"| node_express_app
node_firebase_client -.->|"optional cloud path"| node_firebase_admin
node_server -->|"starts"| node_express_app
node_express_app -->|"protects routes"| node_jwt_auth
node_express_app --> node_auth_routes
node_express_app --> node_ai_routes
node_express_app --> node_calendar_routes
node_express_app --> node_dashboard_routes
node_express_app --> node_social_routes
node_jwt_auth -.->|"user scope"| node_sqlite_queries
node_auth_routes --> node_sqlite_queries
node_ai_routes -->|"jobs and brand voice"| node_sqlite_queries
node_ai_routes -->|"generate"| node_gemini
node_calendar_routes -->|"schedules"| node_sqlite_queries
node_calendar_routes -->|"schedule delivery"| node_scheduler
node_dashboard_routes -->|"aggregate metrics"| node_sqlite_queries
node_social_routes -->|"account state"| node_sqlite_queries
node_social_routes -->|"connect accounts"| node_social_auth
node_social_routes -->|"publish"| node_social_publishers
node_scheduler -->|"deliver planned posts"| node_social_publishers
node_sqlite_queries -->|"native node:sqlite"| node_sqlite
node_firebase_admin -.->|"optional integration"| node_sqlite_queries

click node_spa_entry "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/main.jsx"
click node_auth_ui "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/context/AuthContext.jsx"
click node_product_pages "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/services/api.js"
click node_global_state "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/context/GlobalStateContext.jsx"
click node_firebase_client "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/firebase.js"
click node_server "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/server.js"
click node_express_app "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/app.js"
click node_jwt_auth "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/middleware/auth.js"
click node_auth_routes "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/routes/auth.js"
click node_ai_routes "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/routes/ai.js"
click node_calendar_routes "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/routes/calendar.js"
click node_dashboard_routes "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/routes/dashboard.js"
click node_social_routes "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/routes/social.js"
click node_sqlite_queries "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/db/queries.js"
click node_sqlite "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/db/connection.js"
click node_gemini "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/services/gemini.js"
click node_scheduler "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/services/scheduler.js"
click node_social_auth "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/services/socialAuth.js"
click node_social_publishers "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/services/socialPublishers.js"
click node_firebase_admin "https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/db/firebase.js"

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_spa_entry,node_auth_ui,node_product_pages,node_api_client,node_global_state,node_firebase_client toneBlue
class node_server,node_express_app,node_jwt_auth,node_auth_routes,node_ai_routes,node_calendar_routes,node_dashboard_routes,node_social_routes toneAmber
class node_sqlite_queries,node_sqlite,node_gemini,node_scheduler,node_social_auth,node_social_publishers,node_firebase_admin toneMint
```

## Components

### React SPA

- [SPA entry & shell](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/main.jsx): React/Vite · Bootstraps the routed application. · `frontend/src/main.jsx`
- [Auth context & guards](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/context/AuthContext.jsx): client auth · Holds session state and protects authenticated routes. · `frontend/src/context/AuthContext.jsx`
- [Product workflows](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/App.jsx): React pages · Dashboard, calendar, generation, brand voice, and social views. · `frontend/src/App.jsx`
- [API service layer](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/services/api.js): HTTP client · `frontend/src/services/api.js`
- [Global UI state](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/context/GlobalStateContext.jsx): React context · `frontend/src/context/GlobalStateContext.jsx`
- [Firebase client](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/frontend/src/firebase.js): optional cloud client · `frontend/src/firebase.js`

### Express API

- [Backend process](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/server.js): Node.js entry · Starts the API server. · `backend/src/server.js`
- [Express app](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/app.js): API composition · Composes middleware and domain routers. · `backend/src/app.js`
- [JWT auth middleware](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/middleware/auth.js): security boundary · Establishes authenticated user scope. · `backend/src/middleware/auth.js`
- [Auth routes](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/routes/auth.js): router · `backend/src/routes/auth.js`
- [AI job routes](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/routes/ai.js): router · Manages generation jobs and history. · `backend/src/routes/ai.js`
- [Calendar routes](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/routes/calendar.js): router · Manages campaign schedule entries. · `backend/src/routes/calendar.js`
- [Dashboard routes](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/routes/dashboard.js): router · Serves campaign and engagement metrics. · `backend/src/routes/dashboard.js`
- [Social routes](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/routes/social.js): router · Handles account connection and publishing. · `backend/src/routes/social.js`

### Data & integrations

- [SQLite query layer](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/db/queries.js): tenant data access · Centralized user-scoped persistence queries. · `backend/src/db/queries.js`
- [SQLite database](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/db/connection.js): primary system of record · Stores users, settings, jobs, schedules, and social state. · `backend/src/db/connection.js`
- [Gemini service](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/services/gemini.js): AI integration · Invokes Gemini 2.5 Flash with brand-voice context. · `backend/src/services/gemini.js`
- [Scheduler](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/services/scheduler.js): campaign delivery · Bridges planned content to social delivery. · `backend/src/services/scheduler.js`
- [Social OAuth service](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/services/socialAuth.js): OAuth integration · Manages provider credentials and tokens. · `backend/src/services/socialAuth.js`
- [Social publisher adapters](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/services/socialPublishers.js): platform delivery · Posts through LinkedIn, X, and Meta adapters. · `backend/src/services/socialPublishers.js`
- [Firebase Admin](https://github.com/mrinmoypatratint/social-marketing-saas/blob/main/backend/src/db/firebase.js): optional cloud integration · Optional Firestore and Storage integration. · `backend/src/db/firebase.js`

## Connections

- SPA entry & shell → Auth context & guards
- SPA entry & shell → Product workflows: renders routes
- Auth context & guards → Product workflows: protects
- Product workflows → Global UI state: uses
- Product workflows → API service layer: calls
- API service layer → Express app: HTTP API
- Firebase client → Firebase Admin: optional cloud path
- Backend process → Express app: starts
- Express app → JWT auth middleware: protects routes
- Express app → Auth routes
- Express app → AI job routes
- Express app → Calendar routes
- Express app → Dashboard routes
- Express app → Social routes
- JWT auth middleware → SQLite query layer: user scope
- Auth routes → SQLite query layer
- AI job routes → SQLite query layer: jobs and brand voice
- AI job routes → Gemini service: generate
- Calendar routes → SQLite query layer: schedules
- Calendar routes → Scheduler: schedule delivery
- Dashboard routes → SQLite query layer: aggregate metrics
- Social routes → SQLite query layer: account state
- Social routes → Social OAuth service: connect accounts
- Social routes → Social publisher adapters: publish
- Scheduler → Social publisher adapters: deliver planned posts
- SQLite query layer → SQLite database: native node:sqlite
- Firebase Admin → SQLite query layer: optional integration