agency-project

name	agency-project
description	Provides architecture knowledge for the Social Media Agency SaaS platform. Use when exploring the codebase, adding features, debugging, or asking about project structure, tech stack, conventions, database schema, or design system.

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

1. Always use src/ layout for the Python backend package
2. pyproject.toml is the single source of truth for deps, tools, and config
3. Use uv for package management — uv sync to install, uv lock to update
4. Use nox for task automation — uv run nox -s test, uv run nox -s lint
5. Use ruff for linting and formatting — replaces flake8, isort, black
6. Use mypy in strict mode — full type checking
7. Never mix secrets with structural config — .env for secrets only
8. Always use structlog — never print()
9. Every tenant-scoped table has org_id — multi-tenant isolation
10. Frontend and backend are independently deployable
11. All API routes versioned under /api/v1/
12. Platform integrations are pluggable — implement the abstract PlatformConnector interface
13. Content must go through approval workflow before publishing
14. Analytics are synced via background workers — never block API requests