Architecture

UniSync is a full-stack application with a layered service architecture.

System Overview

Service Layer Pattern

UniSync follows a strict layered architecture. Each layer only communicates with the layer directly below it.

Layer	Responsibility	Location
Routers	HTTP endpoints, request validation, auth	backend/api_server/routers/
Services	Business logic, orchestration	backend/modules/ai_content/services/
Repositories	Database queries (raw SQL)	backend/modules/ai_content/database/repositories/
Models	Pydantic schemas for validation	backend/modules/ai_content/models/

Agent Execution Flow

Quick Publisher

Production Agent — SEO Pipeline

Database Architecture

• Engine: PostgreSQL 15+
• Driver: psycopg2 (raw SQL, no ORM)
• Tables: 38 application tables + alembic_version
• Migrations: Alembic for schema changes
• Schema init: database_init.py runs on startup (creates tables, indexes, constraints)

Key Table Groups

Group	Tables	Purpose
Auth	users, user_sessions, api_credentials	Authentication and credentials
Agents	agents, agent_automation_assignments, agent_planner_assignments	Agent configuration
Content	wordpress_posts, astro_posts, astro_categories, astro_tags	Published content
SEO	seo_keyword_plans, seo_campaign_planners, seo_posts_queue, keyword_registry	SEO pipeline
Scout	scout_opportunities, scout_config, scout_cycle_logs	Trend discovery
Strategy	content_strategies, topic_clusters	Content planning
Analytics	token_usage, model_pricing	Cost tracking

Background Services

UniSync runs several background services alongside the API:

Service	Interval	Purpose
Queue Scheduler	30 seconds	Polls for queued agents and executes them
AutoPilot	Per-environment config	Automatically queues agents on schedule
Scout Scheduler	Configurable	Runs content opportunity discovery cycles
Model Pricing Sync	24 hours	Updates AI model pricing data

Deployment Architecture

unisync.ai          → Landing site (React + Vite, static)
app.unisync.ai      → Frontend application (React SPA)
api.unisync.ai      → Backend API (FastAPI)
docs.unisync.ai     → Documentation (VitePress, static)
bridge.example.com  → Bridge API (Express.js, per Astro site)