aditya-sinha1/social-marketing-saas

Purpose and runtime

SocialGen is a multi-tenant social-marketing SaaS: users generate AI content, apply brand voice, manage campaign schedules, view engagement analytics, and connect publishing accounts. It runs as a React/Vite SPA plus a Node.js/Express API, with native SQLite as the primary local relational store. Node 22+ is material for node:sqlite.

Key entry points: frontend/src/main.jsx, frontend/src/App.jsx, backend/src/server.js, and backend/src/app.js.

Client application and navigation

The SPA owns presentation, client-side routing, authenticated navigation, and API invocation. App.jsx composes application routes/pages; Layout.jsx provides the shared shell; ProtectedRoute.jsx prevents access to product pages without an authenticated session.

State is split between session identity and broader application state in frontend/src/context/AuthContext.jsx and frontend/src/context/GlobalStateContext.jsx. HTTP requests are centralized through frontend/src/services/api.js, forming the client/server boundary.

Primary user-facing workflows are represented by pages including frontend/src/pages/BlogGenerator.jsx, frontend/src/pages/Calendar.jsx, and frontend/src/pages/SocialAccounts.jsx.

API composition and security boundary

Express application setup and route registration are centralized in backend/src/app.js; process startup/listening is in backend/src/server.js. API domains are divided into auth, AI, calendar, dashboard, and social integrations: backend/src/routes/auth.js, backend/src/routes/ai.js, backend/src/routes/calendar.js, backend/src/routes/dashboard.js, and backend/src/routes/social.js.

JWT authentication middleware protects tenant-scoped operations and establishes the authenticated user context before routes access records or external integrations: backend/src/middleware/auth.js. Auth routes register/login users with bcrypt-hashed credentials and expose profile/settings updates.

Persistence and tenant data

SQLite connection/schema lifecycle is owned by backend/src/db/connection.js; reusable persistence operations reside in backend/src/db/queries.js. The main data boundary is authenticated-user ownership: campaigns, AI jobs/history, settings/brand voice, and social connections should be accessed through the route plus auth-context path rather than directly from the frontend.

backend/src/seed_db.js supports initializing representative local data. Firebase has optional admin/document-cloud integration hooks in backend/src/db/firebase.js; repository-level Firebase rules and indexes are defined in firestore.rules and firestore.indexes.json.

AI content-generation pipeline

Authenticated clients submit and manage generation jobs through backend/src/routes/ai.js. The route layer persists job state/history and delegates model interaction to backend/src/services/gemini.js. Gemini 2.5 Flash is the external generation service, authenticated by GEMINI_API_KEY.

Brand personalization flows from per-user settings/profile into generation prompts: the product supports formality, humor, energy, technicality, warmth, and word inclusion/exclusion controls. Results can be retrieved, edited, deleted, retried, and consumed by blog/remix/hashtag UI workflows.

Campaign lifecycle, analytics, and publication

Calendar CRUD is exposed by backend/src/routes/calendar.js and displayed through frontend/src/pages/Calendar.jsx. Scheduling behavior is encapsulated in backend/src/services/scheduler.js, separating campaign persistence from publish-time orchestration.

Dashboard aggregation is served by backend/src/routes/dashboard.js and rendered by frontend/src/pages/Dashboard.jsx; engagement seeding/simulation support is in backend/src/services/engagementSeeder.js.

Social OAuth and publishing are isolated behind backend/src/routes/social.js, backend/src/services/socialAuth.js, and backend/src/services/socialPublishers.js. LinkedIn, Twitter/X, and Meta credentials are optional external dependencies configured through environment variables; OAuth tokens and posting behavior should remain server-side.

Infrastructure and configuration

Backend environment loading/configuration is centralized in backend/src/load_env.js and backend/src/config/index.js; the template is backend/.env.example. Required operational secrets are JWT and Gemini keys; OAuth client secrets are also backend-only. Frontend Firebase client initialization exists at frontend/src/firebase.js, while Firebase deployment configuration is in firebase.json.