Skip to main content

System Overview

II-Agent is a domain-driven FastAPI + Socket.IO platform. The backend is organized into bounded areas under src/ii_agent/, while the frontend and docs live alongside it in the same repo.

Domain Map​

src/ii_agent/
├── app/            # FastAPI app factory, router registration, lifespan
├── core/           # Config, DB, Redis, storage, middleware, container
├── auth/           # OAuth, JWT, session-level auth helpers
├── users/          # Profiles and API keys
├── billing/        # Billing transactions and Stripe flows
├── credits/        # Credit balances, ledger, usage handling
├── tasks/          # Canonical run/task lifecycle tracking
├── sessions/       # Session CRUD, pins, wishlists, titles
├── chat/           # REST chat APIs, providers, messages, runs, media
├── agents/         # Runtime loop, plans, tools, skills, sandboxes, models
├── realtime/       # Socket.IO manager, handlers, events, pubsub
├── content/        # Slides, storybooks, media templates
├── files/          # User and session assets
├── projects/       # Cloud Run, databases, deployments, secrets, subdomains
├── integrations/   # Connectors, prompt enhancement, mobile
├── settings/       # Model, MCP, and skills settings
└── workers/        # Celery tasks and cron jobs

Layering Rules​

Within each domain, dependencies flow downward:

router → dependencies → service → repository → models

That means:

  • routers do not query the database directly
  • services hold business logic
  • repositories own data access
  • schemas stay separate from ORM models

Startup Sequence​

The application lifespan follows this rough order:

  1. Initialize the database engine and pool.
  2. Initialize Redis.
  3. Run Alembic migrations unless skipped.
  4. Build the application container.
  5. Attach pubsub subscribers for Socket.IO and event persistence.
  6. Register Socket.IO handlers.
  7. Seed built-in settings and skills.
  8. Start scheduled jobs.

Request Flow​

HTTP​

Client → middleware → router → service → repository → DB/external APIs → response schema

Realtime​

Client → Socket.IO auth → command handler → agent/runtime services → pubsub → frontend events

Event System​

Handlers publish structured events into pubsub. Two major subscribers consume them:

  • Socket.IO delivery to connected clients
  • Database persistence into application_events

This keeps frontend streaming and backend auditability aligned on the same event contract.

Architectural Constraints​

  • UUID primary keys are the default across the ORM.
  • Services and repositories should use dependency aliases instead of bare Depends.
  • Billable LLM/tool work must go through the credit reservation path.
  • New LLM-touching code should align with shared execution/billing abstractions instead of ad hoc calls.

Where To Go Next​