Social Media Agency — Project Architecture
Project Context
Social Media Agency is a full-service SaaS platform for social media agencies. Agencies subscribe and manage multiple client accounts, plan campaigns, create AI-powered content, schedule posts across platforms, run approval workflows, and track analytics — all from a single dashboard. The platform is platform-agnostic by design: social media integrations are abstracted so new platforms can be added without changing the core. Sold as "Agency as a Service" with tiered subscriptions via Stripe.
Tech Stack
| Layer |
Technology |
| Backend Framework |
FastAPI (Python 3.12+) |
| Package Manager |
uv (lockfile: uv.lock) |
| Task Runner |
Nox + nox-uv |
| Linter / Formatter |
Ruff |
| Type Checker |
mypy (strict mode) |
| Frontend Framework |
Next.js 14 (App Router), React 18, TypeScript |
| Database |
PostgreSQL 16, SQLAlchemy 2.0 (async), Alembic |
| Cache / Queue |
Redis, Celery |
| Auth |
JWT (python-jose) + OAuth2 (Google SSO) |
| UI Components |
shadcn/ui, Radix UI, Tailwind CSS |
| State Management |
Zustand, TanStack Query |
| Charts |
Recharts |
| LLM |
OpenAI GPT-4o (primary), Claude (fallback) |
| Image Generation |
OpenAI DALL-E 3 |
| Billing |
Stripe (subscriptions + usage metering) |
| Media Storage |
AWS S3 / MinIO |
| Email |
AgentMail (client comms + outreach) |
| Deployment |
Docker, Docker Compose, GitHub Actions |
| Monitoring |
Sentry, Prometheus, Grafana |
Project Structure
social-media-agency/
├── backend/
│ ├── src/agency/ # Python package (src-layout)
│ │ ├── __init__.py
│ │ ├── main.py # FastAPI app factory
│ │ ├── config.py # Pydantic Settings
│ │ ├── dependencies.py # DI: DB, current_user, org
│ │ ├── routers/
│ │ │ ├── health.py
│ │ │ ├── auth.py
│ │ │ ├── organizations.py
│ │ │ ├── clients.py
│ │ │ ├── campaigns.py
│ │ │ ├── content.py
│ │ │ ├── calendar.py
│ │ │ ├── platforms.py
│ │ │ ├── approvals.py
│ │ │ ├── analytics.py
│ │ │ ├── assets.py
│ │ │ ├── reports.py
│ │ │ └── billing.py
│ │ ├── services/
│ │ │ ├── ai_engine.py # LLM content generation
│ │ │ ├── content_service.py
│ │ │ ├── campaign_service.py
│ │ │ ├── scheduling_service.py
│ │ │ ├── analytics_service.py
│ │ │ ├── platform_service.py # Platform integration abstraction
│ │ │ ├── approval_service.py
│ │ │ ├── asset_service.py
│ │ │ └── billing_service.py
│ │ ├── models/
│ │ │ ├── database.py # SQLAlchemy async engine
│ │ │ ├── tables.py # ORM models
│ │ │ └── schemas.py # Pydantic request/response
│ │ ├── middleware/
│ │ │ ├── tenant.py # Multi-tenant context
│ │ │ └── auth.py
│ │ ├── workers/ # Celery tasks
│ │ │ ├── publishing_worker.py # Post publishing
│ │ │ ├── analytics_worker.py # Metrics sync
│ │ │ ├── report_worker.py # Client report generation
│ │ │ └── email_worker.py
│ │ ├── integrations/ # Platform connectors
│ │ │ ├── base.py # Abstract platform interface
│ │ │ ├── instagram.py
│ │ │ ├── facebook.py
│ │ │ ├── twitter.py
│ │ │ ├── linkedin.py
│ │ │ └── tiktok.py
│ │ ├── websocket/
│ │ │ ├── notifications.py # Real-time notifications
│ │ │ └── collaboration.py # Live content editing
│ │ └── utils/
│ │ └── logger.py # structlog setup
│ ├── alembic/
│ ├── tests/
│ ├── pyproject.toml # Single source of truth (deps, tools, config)
│ ├── uv.lock
│ ├── noxfile.py
│ └── Dockerfile
├── frontend/
│ ├── src/
│ │ ├── app/ # Next.js App Router
│ │ │ ├── (auth)/
│ │ │ │ ├── login/page.tsx
│ │ │ │ └── signup/page.tsx
│ │ │ ├── (dashboard)/
│ │ │ │ ├── layout.tsx # Sidebar + topbar shell
│ │ │ │ ├── page.tsx # Overview / home
│ │ │ │ ├── clients/
│ │ │ │ ├── campaigns/
│ │ │ │ ├── content/
│ │ │ │ ├── calendar/
│ │ │ │ ├── analytics/
│ │ │ │ ├── assets/
│ │ │ │ ├── approvals/
│ │ │ │ └── settings/
│ │ │ └── reports/
│ │ │ └── [reportId]/page.tsx
│ │ ├── components/
│ │ │ ├── ui/ # shadcn/ui primitives
│ │ │ ├── content/ # Content editor, preview, AI tools
│ │ │ ├── calendar/ # Calendar views, drag-drop
│ │ │ ├── analytics/ # Charts, KPI cards, tables
│ │ │ ├── campaigns/ # Campaign cards, timelines
│ │ │ └── layout/ # Sidebar, topbar, mobile nav
│ │ ├── lib/
│ │ │ ├── api.ts # Typed API client
│ │ │ ├── socket.ts # WebSocket client
│ │ │ └── utils.ts # cn() helper
│ │ ├── hooks/
│ │ │ ├── use-content.ts
│ │ │ ├── use-campaigns.ts
│ │ │ └── use-auth.ts
│ │ └── types/
│ │ └── index.ts
│ ├── public/
│ ├── package.json
│ └── Dockerfile
├── db/
│ ├── init.sql # Schema DDL
│ └── seed.sql # Demo data
├── docker/
│ └── docker-compose.yml
├── .cursor/skills/ # Cursor AI skills
├── .github/workflows/
├── .env.example
└── README.md
Database Schema
| Table |
Purpose |
Key Columns |
organization |
Agency tenant |
id (UUID), name, domain, settings (JSON) |
users |
Agency team members |
id (UUID), org_id (FK), email, role, password_hash |
subscription |
Stripe billing |
id (UUID), org_id (FK), stripe_subscription_id, plan_tier, clients_limit, posts_limit |
client |
Managed client/brand |
id (UUID), org_id (FK), brand_name, industry, description, logo_url, settings (JSON) |
platform_account |
Connected social account |
id (UUID), client_id (FK), platform, account_handle, access_token_enc, status |
campaign |
Marketing campaign |
id (UUID), client_id (FK), org_id (FK), name, objective, start_date, end_date, status, budget (JSON) |
content |
Content piece (post) |
id (UUID), campaign_id (FK), client_id (FK), org_id (FK), body, media_urls (JSON), hashtags (JSON), platform, status, scheduled_at |
content_schedule |
Publishing schedule entry |
id (UUID), content_id (FK), platform_account_id (FK), scheduled_at, published_at, external_post_id, status |
approval |
Approval workflow entry |
id (UUID), content_id (FK), reviewer_id (FK), status, feedback, decided_at |
asset |
Media library item |
id (UUID), org_id (FK), client_id (FK), filename, s3_key, mime_type, size_bytes, tags (JSON) |
analytics_snapshot |
Performance metrics |
id (UUID), platform_account_id (FK), content_id (FK), date, impressions, reach, engagement, clicks, followers_delta (JSON) |
client_report |
Generated client report |
id (UUID), client_id (FK), period_start, period_end, metrics_summary (JSON), ai_insights, report_url |
User Roles (RBAC)
| Role |
Permissions |
| Admin |
Full org access, billing, user management, all clients |
| Manager |
Manage clients, campaigns, approve content, view analytics |
| Content Creator |
Create/edit content, upload assets, request approvals |
| Viewer |
Read-only access to content, analytics, and reports |
User Journeys
Agency Owner Flow
Sign up → Create org → Subscribe (Stripe) → Add team members
→ Add client → Connect client's social accounts
→ Create campaign → Assign content creators
→ Review & approve content → Track analytics → Send client reports
Content Creator Flow
Log in → View assigned clients/campaigns → Create content (AI-assisted)
→ Upload media assets → Schedule posts → Submit for approval
→ Revise if needed → Content auto-publishes at scheduled time
Client Report Flow
Analytics sync runs (Celery) → Aggregate metrics per client
→ AI generates insights → Report PDF created
→ Email sent via AgentMail with report attached
Design System
- Background: Slate-50 to white gradient (light theme primary)
- Primary accent: Indigo-600 (#4f46e5)
- Success: Emerald-500 (#10b981)
- Warning: Amber-500 (#f59e0b)
- Danger: Red-500 (#ef4444)
- Text: Slate-900 primary, Slate-500 secondary
- Font: Inter (body + headings)
- Cards:
bg-white border border-slate-200 rounded-xl shadow-sm
- Calendar: Full-width grid with drag-drop support, color-coded by platform/client
Environment Variables
| Variable |
Scope |
Purpose |
DATABASE_URL |
Backend |
PostgreSQL async connection |
REDIS_URL |
Backend |
Redis connection |
JWT_SECRET |
Backend |
Token signing |
OPENAI_API_KEY |
Backend |
GPT-4o for AI content + DALL-E |
ANTHROPIC_API_KEY |
Backend |
Claude fallback |
STRIPE_SECRET_KEY |
Backend |
Stripe API |
STRIPE_WEBHOOK_SECRET |
Backend |
Webhook verification |
AWS_ACCESS_KEY_ID |
Backend |
S3 media storage |
AWS_SECRET_ACCESS_KEY |
Backend |
S3 media storage |
S3_BUCKET_NAME |
Backend |
Media bucket |
AGENTMAIL_API_KEY |
Backend |
AgentMail email API |
AGENTMAIL_DEFAULT_DOMAIN |
Backend |
Custom email domain |
NEXT_PUBLIC_API_URL |
Frontend |
Backend API base URL |
NEXT_PUBLIC_STRIPE_KEY |
Frontend |
Stripe publishable key |
Naming Conventions
| Used for |
Style |
Example |
| Python package, files |
snake_case |
agency, ai_engine.py |
| Python classes |
PascalCase |
ContentService, CampaignResponse |
| API routes |
kebab-case |
/api/v1/platform-accounts |
| DB tables |
snake_case |
platform_account, content_schedule |
| Next.js components |
PascalCase |
ContentEditor.tsx, KPICard.tsx |
| Next.js pages/dirs |
kebab-case |
campaigns/, [reportId]/ |
| CSS/Tailwind |
kebab-case |
text-slate-900, bg-indigo-600 |
| Env vars |
UPPER_SNAKE_CASE |
OPENAI_API_KEY |
Key Rules
- Always use
src/ layout for the Python backend package
pyproject.toml is the single source of truth for deps, tools, and config
- Use
uv for package management — uv sync to install, uv lock to update
- Use
nox for task automation — uv run nox -s test, uv run nox -s lint
- Use
ruff for linting and formatting — replaces flake8, isort, black
- Use
mypy in strict mode — full type checking
- Never mix secrets with structural config —
.env for secrets only
- Always use structlog — never
print()
- Every tenant-scoped table has
org_id — multi-tenant isolation
- Frontend and backend are independently deployable
- All API routes versioned under
/api/v1/
- Platform integrations are pluggable — implement the abstract
PlatformConnector interface
- Content must go through approval workflow before publishing
- Analytics are synced via background workers — never block API requests