How mrinmoypatratint/social-marketing-saas works
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: app.js Express app · queries.js SQLite query layer · social.js Social routes · App.jsx Product workflows
Components 21
React SPA
- SPA entry & shell · Bootstraps the routed application.
frontend/src/main.jsx - Auth context & guards · Holds session state and protects authenticated routes.
frontend/src/context/AuthContext.jsx - Product workflows · Dashboard, calendar, generation, brand voice, and social views.
frontend/src/App.jsx - API service layer
frontend/src/services/api.js - Global UI state
frontend/src/context/GlobalStateContext.jsx - Firebase client
frontend/src/firebase.js
Express API
- Backend process · Starts the API server.
backend/src/server.js - Express app · Composes middleware and domain routers.
backend/src/app.js - JWT auth middleware · Establishes authenticated user scope.
backend/src/middleware/auth.js - Auth routes
backend/src/routes/auth.js - AI job routes · Manages generation jobs and history.
backend/src/routes/ai.js - Calendar routes · Manages campaign schedule entries.
backend/src/routes/calendar.js - Dashboard routes · Serves campaign and engagement metrics.
backend/src/routes/dashboard.js - Social routes · Handles account connection and publishing.
backend/src/routes/social.js
Data & integrations
- SQLite query layer · Centralized user-scoped persistence queries.
backend/src/db/queries.js - SQLite database · Stores users, settings, jobs, schedules, and social state.
backend/src/db/connection.js - Gemini service · Invokes Gemini 2.5 Flash with brand-voice context.
backend/src/services/gemini.js - Scheduler · Bridges planned content to social delivery.
backend/src/services/scheduler.js - Social OAuth service · Manages provider credentials and tokens.
backend/src/services/socialAuth.js - Social publisher adapters · Posts through LinkedIn, X, and Meta adapters.
backend/src/services/socialPublishers.js - Firebase Admin · Optional Firestore and Storage integration.
backend/src/db/firebase.js
Connections 27
- 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