Architecture Overview
OpenSNS follows a clean separation between frontend, backend, and AI services.
System Diagram
Section titled “System Diagram”┌─────────────────────────────────────────────────────────────────┐│ Client Layer ││ ┌─────────────────────────────────────────────────────────┐ ││ │ Next.js 15 Frontend │ ││ │ • React Query for data fetching │ ││ │ • shadcn/ui components │ ││ │ • WebSocket for real-time updates │ ││ └─────────────────────────────────────────────────────────┘ │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ API Layer ││ ┌─────────────────────────────────────────────────────────┐ ││ │ FastAPI Backend │ ││ │ • REST API endpoints │ ││ │ • JWT authentication │ ││ │ • WebSocket handlers │ ││ │ • Rate limiting │ ││ └─────────────────────────────────────────────────────────┘ │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ Service Layer ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ││ │ Research │ │ Pipeline │ │ Engines │ ││ │ Service │ │ Orchestrator│ │ Registry │ ││ └──────────────┘ └──────────────┘ └──────────────┘ │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ Agent Layer ││ ┌─────────────────────────────────────────────────────────┐ ││ │ LangGraph Workflow │ ││ │ │ ││ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ ││ │ │Rsrch │──▶│Strat │──▶│Copy │──▶│Image │──▶│Video │ │ ││ │ └──────┘ └──────┘ └──────┘ └──────┘ └──────┘ │ ││ │ │ ││ └─────────────────────────────────────────────────────────┘ │└─────────────────────────────────────────────────────────────────┘ │ ▼┌─────────────────────────────────────────────────────────────────┐│ External Services ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ OpenAI │ │ Fal.ai │ │ Ollama │ │ ComfyUI │ ││ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │└─────────────────────────────────────────────────────────────────┘Component Details
Section titled “Component Details”Frontend (Next.js 15)
Section titled “Frontend (Next.js 15)”| Component | Purpose |
|---|---|
| App Router | File-based routing with layouts |
| React Query | Server state management |
| shadcn/ui | Accessible UI components |
| Tailwind CSS | Utility-first styling |
| WebSocket | Real-time agent updates |
Backend (FastAPI)
Section titled “Backend (FastAPI)”| Component | Purpose |
|---|---|
| API Routes | REST endpoints for all operations |
| SQLModel | ORM with Pydantic validation |
| JWT Auth | Stateless authentication |
| WebSocket | Broadcast agent logs |
| Rate Limiting | Prevent abuse |
Agent Layer (LangGraph)
Section titled “Agent Layer (LangGraph)”The AI pipeline uses LangGraph for:
- Stateful execution - Tracks progress across nodes
- Checkpointing - Resume from interrupts
- Parallel execution - Run independent tasks concurrently
- Error handling - Graceful fallbacks
Engine Registry
Section titled “Engine Registry”Pluggable AI backends:
engine_registry.register_llm_engine("openai", OpenAIAdapter)engine_registry.register_llm_engine("ollama", OllamaAdapter)engine_registry.register_image_engine("fal", FalImageAdapter)Data Flow
Section titled “Data Flow”- User creates campaign → API receives request
- Background task starts → Pipeline orchestrator begins
- Research node → Scrapes product URL
- Strategy node → Generates marketing angles
- Copy node → Creates ad copy for each angle/platform
- Image node → Generates product images
- Video node → Converts images to videos
- Assets saved → Stored in database
- WebSocket broadcast → UI updates in real-time
Database Schema
Section titled “Database Schema”User (1) ──────────────────── (N) Campaign │ │ │ │ └── (1) UserSettings (N) Asset │ (N) AgentLogSecurity Model
Section titled “Security Model”- JWT tokens in Authorization header
- Encrypted API keys stored with Fernet
- Rate limiting on sensitive endpoints
- SSRF protection on asset export