# sharadwowevents/wowos_bot architecture

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

- Interactive diagram: https://gitdiagram.com/sharadwowevents/wowos_bot
- Repository: https://github.com/sharadwowevents/wowos_bot

## Overview

WOWOS Bot API is a FastAPI conversational assistant backed by MongoDB and OpenAI. A client first creates a session using an email; the service resolves the user’s profile and stores role and permissions with a generated session ID. The client then asks questions using that ID, and the answer flow continues the OpenAI conversation with read-only MongoDB tools. The main implementation is a monolith in main.py; unsampled details of its question route and tool loop are represented only where the README documents them.

Main entry points: [`main.py`](https://github.com/sharadwowevents/wowos_bot/blob/main/main.py) (Answer orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API workflow"]
  node_fastapi["FastAPI service<br/>[main.py]"]
  node_question["Question endpoint<br/>[main.py]"]
end

subgraph group_identity["Identity and sessions"]
  node_user_session["Create session<br/>[main.py]"]
  node_profile_lookup["Profile lookup<br/>[main.py]"]
  node_sessions[("Session state<br/>[main.py]")]
end

subgraph group_answering["Question answering"]
  node_answer_flow["Answer orchestration<br/>[main.py]"]
  node_openai["OpenAI Responses"]
  node_tool_dispatch["Tool dispatch<br/>[main.py]"]
end

subgraph group_data["MongoDB access"]
  node_mongo_tools["Read-only query tools<br/>[main.py]"]
  node_mongodb[("MongoDB")]
end

node_client(("API client"))

node_client -->|"calls API"| node_fastapi
node_fastapi -->|"routes session"| node_user_session
node_user_session -->|"resolves profile"| node_profile_lookup
node_profile_lookup -->|"reads user and profile"| node_mongodb
node_user_session -->|"stores context"| node_sessions
node_fastapi -->|"routes question"| node_question
node_question -->|"loads session"| node_sessions
node_question -->|"processes question"| node_answer_flow
node_answer_flow -->|"requests response"| node_openai
node_answer_flow -->|"continues conversation"| node_sessions
node_openai -->|"requests tool"| node_tool_dispatch
node_tool_dispatch -->|"dispatches call"| node_mongo_tools
node_mongo_tools -->|"queries data"| node_mongodb
node_answer_flow -->|"saves response state"| node_sessions
node_answer_flow -->|"returns answer"| node_client

click node_fastapi "https://github.com/sharadwowevents/wowos_bot/blob/main/main.py"
click node_user_session "https://github.com/sharadwowevents/wowos_bot/blob/main/main.py"
click node_profile_lookup "https://github.com/sharadwowevents/wowos_bot/blob/main/main.py"
click node_sessions "https://github.com/sharadwowevents/wowos_bot/blob/main/main.py"
click node_question "https://github.com/sharadwowevents/wowos_bot/blob/main/main.py"
click node_answer_flow "https://github.com/sharadwowevents/wowos_bot/blob/main/main.py"
click node_tool_dispatch "https://github.com/sharadwowevents/wowos_bot/blob/main/main.py"
click node_mongo_tools "https://github.com/sharadwowevents/wowos_bot/blob/main/main.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_fastapi,node_question,node_client toneBlue
class node_user_session,node_profile_lookup,node_sessions toneAmber
class node_answer_flow,node_openai,node_tool_dispatch toneMint
class node_mongo_tools,node_mongodb toneRose
```

## Components

### API workflow

- [FastAPI service](https://github.com/sharadwowevents/wowos_bot/blob/main/main.py): `main.py`
- [Question endpoint](https://github.com/sharadwowevents/wowos_bot/blob/main/main.py): `main.py`

### Identity and sessions

- [Create session](https://github.com/sharadwowevents/wowos_bot/blob/main/main.py): `main.py`
- [Profile lookup](https://github.com/sharadwowevents/wowos_bot/blob/main/main.py): `main.py`
- [Session state](https://github.com/sharadwowevents/wowos_bot/blob/main/main.py): `main.py`

### Question answering

- [Answer orchestration](https://github.com/sharadwowevents/wowos_bot/blob/main/main.py): `main.py`
- **OpenAI Responses**
- [Tool dispatch](https://github.com/sharadwowevents/wowos_bot/blob/main/main.py): `main.py`

### MongoDB access

- [Read-only query tools](https://github.com/sharadwowevents/wowos_bot/blob/main/main.py): `main.py`
- **MongoDB**

### Other components

- **API client**

## Connections

- API client → FastAPI service: calls API (evidence: `readme.md`)
- FastAPI service → Create session: routes session (evidence: `readme.md`)
- Create session → Profile lookup: resolves profile (evidence: `main.py`)
- Profile lookup → MongoDB: reads user and profile (evidence: `main.py`)
- Create session → Session state: stores context (evidence: `main.py`)
- FastAPI service → Question endpoint: routes question (evidence: `readme.md`)
- Question endpoint → Session state: loads session (evidence: `readme.md`)
- Question endpoint → Answer orchestration: processes question (evidence: `readme.md`)
- Answer orchestration → OpenAI Responses: requests response (evidence: `main.py`)
- Answer orchestration → Session state: continues conversation (evidence: `readme.md`)
- OpenAI Responses → Tool dispatch: requests tool (evidence: `main.py`)
- Tool dispatch → Read-only query tools: dispatches call (evidence: `main.py`)
- Read-only query tools → MongoDB: queries data (evidence: `main.py`)
- Answer orchestration → Session state: saves response state (evidence: `readme.md`)
- Answer orchestration → API client: returns answer (evidence: `readme.md`)