# jumon000/swarm architecture

> Architecture diagram of the GitHub repository jumon000/swarm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jumon000/swarm
- Repository: https://github.com/jumon000/swarm

## Overview

Event Logistics Swarm is a FastAPI service for event organizers: users authenticate, create events and manage participants, then request either a full or focused AI workflow and receive schedules, marketing content, communications, and analytics. The documented full workflow loads event context and participant data, runs scheduler, content, mail, and analytics stages, then saves results. The README describes capabilities beyond the sampled excerpts; those branches are represented at their documented module paths, while uncertain implementation-level links are omitted.

Main entry points: [`app/orchestration/langgraph_workflow.py`](https://github.com/jumon000/swarm/blob/main/app/orchestration/langgraph_workflow.py) (LangGraph workflow), [`app/database/models.py`](https://github.com/jumon000/swarm/blob/main/app/database/models.py) (PostgreSQL data), [`app/main.py`](https://github.com/jumon000/swarm/blob/main/app/main.py) (FastAPI app), [`app/api/auth_routes.py`](https://github.com/jumon000/swarm/blob/main/app/api/auth_routes.py) (Authentication routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Access"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth_routes.py]"]
  node_auth_service["Authentication service<br/>[auth_service.py]"]
end

subgraph group_event["Event Operations"]
  node_event_routes["Event routes<br/>[event_routes.py]"]
  node_participant_routes["Participant routes"]
  node_csv_parser["CSV import<br/>[csv_parser.py]"]
  node_schedule_service["Schedule service"]
  node_email_service["Email service<br/>[email_service.py]"]
end

subgraph group_agents["Agent Workflow"]
  node_agent_routes["Agent routes<br/>[agent_routes.py]"]
  node_workflow["LangGraph workflow"]
  node_workflow_state["Shared state<br/>[state_schema.py]"]
  node_scheduler["Scheduler agent<br/>[scheduler_agent.py]"]
  node_content_agent["Content agent<br/>[content_agent.py]"]
  node_mail_agent["Mail agent<br/>[mail_agent.py]"]
  node_analytics_agent["Analytics agent<br/>[analytics_agent.py]"]
end

subgraph group_state["Persistence and Memory"]
  node_postgres[("PostgreSQL data<br/>[models.py]")]
  node_db_session["Database sessions<br/>[session.py]"]
  node_vector_memory[("Vector memory<br/>[vector_store.py]")]
end

node_organizer(("Organizer"))
node_openai{{"OpenAI API"}}
node_smtp{{"SMTP server"}}

node_organizer -->|"sends requests"| node_api_app
node_api_app -->|"dispatches auth"| node_auth_routes
node_api_app -->|"dispatches events"| node_event_routes
node_api_app -->|"dispatches participants"| node_participant_routes
node_api_app -->|"dispatches workflows"| node_agent_routes
node_auth_routes -->|"authenticates users"| node_auth_service
node_auth_routes -->|"uses sessions"| node_db_session
node_auth_service -->|"queries users"| node_postgres
node_event_routes -->|"reads and writes"| node_db_session
node_participant_routes -->|"reads and writes"| node_db_session
node_participant_routes -->|"parses uploads"| node_csv_parser
node_agent_routes -->|"loads event data"| node_db_session
node_agent_routes -->|"runs workflow"| node_workflow
node_workflow -->|"updates state"| node_workflow_state
node_workflow -->|"loads context"| node_vector_memory
node_workflow -->|"dispatches stage"| node_scheduler
node_workflow -->|"dispatches stage"| node_content_agent
node_workflow -->|"dispatches stage"| node_mail_agent
node_workflow -->|"dispatches stage"| node_analytics_agent
node_scheduler -->|"generates schedule"| node_schedule_service
node_mail_agent -->|"prepares and sends"| node_email_service
node_email_service -->|"sends email"| node_smtp
node_mail_agent -->|"logs emails"| node_postgres
node_content_agent -->|"generates content"| node_openai
node_mail_agent -->|"generates templates"| node_openai
node_scheduler -.->|"requests generation"| node_openai
node_analytics_agent -.->|"requests insights"| node_openai
node_workflow -->|"saves results"| node_postgres
node_workflow -->|"stores summaries"| node_vector_memory
node_event_routes -->|"persists events"| node_postgres
node_participant_routes -->|"persists participants"| node_postgres
node_auth_routes -->|"persists accounts"| node_postgres

click node_api_app "https://github.com/jumon000/swarm/blob/main/app/main.py"
click node_auth_routes "https://github.com/jumon000/swarm/blob/main/app/api/auth_routes.py"
click node_auth_service "https://github.com/jumon000/swarm/blob/main/app/services/auth_service.py"
click node_event_routes "https://github.com/jumon000/swarm/blob/main/app/api/event_routes.py"
click node_participant_routes "https://github.com/jumon000/swarm/blob/main/app/api/participant_routes.py"
click node_csv_parser "https://github.com/jumon000/swarm/blob/main/app/services/csv_parser.py"
click node_agent_routes "https://github.com/jumon000/swarm/blob/main/app/api/agent_routes.py"
click node_workflow "https://github.com/jumon000/swarm/blob/main/app/orchestration/langgraph_workflow.py"
click node_workflow_state "https://github.com/jumon000/swarm/blob/main/app/orchestration/state_schema.py"
click node_scheduler "https://github.com/jumon000/swarm/blob/main/app/agents/scheduler_agent.py"
click node_schedule_service "https://github.com/jumon000/swarm/blob/main/app/services/schedule_service.py"
click node_content_agent "https://github.com/jumon000/swarm/blob/main/app/agents/content_agent.py"
click node_mail_agent "https://github.com/jumon000/swarm/blob/main/app/agents/mail_agent.py"
click node_analytics_agent "https://github.com/jumon000/swarm/blob/main/app/agents/analytics_agent.py"
click node_email_service "https://github.com/jumon000/swarm/blob/main/app/services/email_service.py"
click node_postgres "https://github.com/jumon000/swarm/blob/main/app/database/models.py"
click node_db_session "https://github.com/jumon000/swarm/blob/main/app/database/session.py"
click node_vector_memory "https://github.com/jumon000/swarm/blob/main/app/memory/vector_store.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_app,node_auth_routes,node_auth_service toneBlue
class node_event_routes,node_participant_routes,node_csv_parser,node_schedule_service,node_email_service toneAmber
class node_agent_routes,node_workflow,node_workflow_state,node_scheduler,node_content_agent,node_mail_agent,node_analytics_agent,node_openai,node_smtp toneMint
class node_postgres,node_db_session,node_vector_memory toneRose
class node_organizer toneIndigo
```

## Components

### API and Access

- [FastAPI app](https://github.com/jumon000/swarm/blob/main/app/main.py): `app/main.py`
- [Authentication routes](https://github.com/jumon000/swarm/blob/main/app/api/auth_routes.py): `app/api/auth_routes.py`
- [Authentication service](https://github.com/jumon000/swarm/blob/main/app/services/auth_service.py): `app/services/auth_service.py`

### Event Operations

- [Event routes](https://github.com/jumon000/swarm/blob/main/app/api/event_routes.py): `app/api/event_routes.py`
- [Participant routes](https://github.com/jumon000/swarm/blob/main/app/api/participant_routes.py): `app/api/participant_routes.py`
- [CSV import](https://github.com/jumon000/swarm/blob/main/app/services/csv_parser.py): `app/services/csv_parser.py`
- [Schedule service](https://github.com/jumon000/swarm/blob/main/app/services/schedule_service.py): `app/services/schedule_service.py`
- [Email service](https://github.com/jumon000/swarm/blob/main/app/services/email_service.py): `app/services/email_service.py`

### Agent Workflow

- [Agent routes](https://github.com/jumon000/swarm/blob/main/app/api/agent_routes.py): `app/api/agent_routes.py`
- [LangGraph workflow](https://github.com/jumon000/swarm/blob/main/app/orchestration/langgraph_workflow.py): `app/orchestration/langgraph_workflow.py`
- [Shared state](https://github.com/jumon000/swarm/blob/main/app/orchestration/state_schema.py): `app/orchestration/state_schema.py`
- [Scheduler agent](https://github.com/jumon000/swarm/blob/main/app/agents/scheduler_agent.py): `app/agents/scheduler_agent.py`
- [Content agent](https://github.com/jumon000/swarm/blob/main/app/agents/content_agent.py): `app/agents/content_agent.py`
- [Mail agent](https://github.com/jumon000/swarm/blob/main/app/agents/mail_agent.py): `app/agents/mail_agent.py`
- [Analytics agent](https://github.com/jumon000/swarm/blob/main/app/agents/analytics_agent.py): `app/agents/analytics_agent.py`

### Persistence and Memory

- [PostgreSQL data](https://github.com/jumon000/swarm/blob/main/app/database/models.py): `app/database/models.py`
- [Database sessions](https://github.com/jumon000/swarm/blob/main/app/database/session.py): `app/database/session.py`
- [Vector memory](https://github.com/jumon000/swarm/blob/main/app/memory/vector_store.py): `app/memory/vector_store.py`

### Other components

- **Organizer**
- **OpenAI API**
- **SMTP server**

## Connections

- Organizer → FastAPI app: sends requests
- FastAPI app → Authentication routes: dispatches auth
- FastAPI app → Event routes: dispatches events
- FastAPI app → Participant routes: dispatches participants
- FastAPI app → Agent routes: dispatches workflows
- Authentication routes → Authentication service: authenticates users
- Authentication routes → Database sessions: uses sessions
- Authentication service → PostgreSQL data: queries users
- Event routes → Database sessions: reads and writes
- Participant routes → Database sessions: reads and writes
- Participant routes → CSV import: parses uploads
- Agent routes → Database sessions: loads event data
- Agent routes → LangGraph workflow: runs workflow
- LangGraph workflow → Shared state: updates state
- LangGraph workflow → Vector memory: loads context
- LangGraph workflow → Scheduler agent: dispatches stage
- LangGraph workflow → Content agent: dispatches stage
- LangGraph workflow → Mail agent: dispatches stage
- LangGraph workflow → Analytics agent: dispatches stage
- Scheduler agent → Schedule service: generates schedule
- Mail agent → Email service: prepares and sends
- Email service → SMTP server: sends email
- Mail agent → PostgreSQL data: logs emails
- Content agent → OpenAI API: generates content
- Mail agent → OpenAI API: generates templates
- Scheduler agent → OpenAI API: requests generation
- Analytics agent → OpenAI API: requests insights
- LangGraph workflow → PostgreSQL data: saves results
- LangGraph workflow → Vector memory: stores summaries
- Event routes → PostgreSQL data: persists events
- Participant routes → PostgreSQL data: persists participants
- Authentication routes → PostgreSQL data: persists accounts