# gokkul-ks/placebot architecture

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

- Interactive diagram: https://gitdiagram.com/gokkul-ks/placebot
- Repository: https://github.com/gokkul-ks/placebot

## Overview

PlaceBot is a placement-preparation chatbot delivered as a FastAPI service with a single-page chat interface. A user submits a message; the response engine handles conversational shortcuts, searches the curated Q&A dataset semantically, optionally expands short keyword queries, then routes by confidence to a dataset answer, Ollama, or a fallback. Configuration, request/response models, and the UI are supporting product layers. The sampled sources establish the chatbot’s internal dependencies; the README documents the API and major capabilities. main.py and the UI source were not sampled, so their implementation-level wiring is not asserted.

Main entry points: [`chatbot.py`](https://github.com/gokkul-ks/placebot/blob/main/chatbot.py) (Response router), [`main.py`](https://github.com/gokkul-ks/placebot/blob/main/main.py) (FastAPI service), [`static/index.html`](https://github.com/gokkul-ks/placebot/blob/main/static/index.html) (Chat UI), [`ollama_client.py`](https://github.com/gokkul-ks/placebot/blob/main/ollama_client.py) (Ollama client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Chat Experience"]
  node_ui["Chat UI<br/>[index.html]"]
  node_api["FastAPI service<br/>[main.py]"]
  node_models["API models<br/>[schemas.py]"]
end

subgraph group_engine["Response Engine"]
  node_chatbot["Response router<br/>[chatbot.py]"]
  node_rules["Text rules<br/>[text_utils.py]"]
end

subgraph group_knowledge["Knowledge Search"]
  node_semantic["Semantic matching<br/>[chatbot.py]"]
  node_dataset[("Placement Q&amp;A<br/>[data.csv]")]
end

subgraph group_integrations["Configuration &amp; Integrations"]
  node_config["Settings<br/>[config.py]"]
  node_ollama_client["Ollama client<br/>[ollama_client.py]"]
end

node_user(("Chat user"))
node_ollama["Ollama service"]

node_user -->|"asks"| node_ui
node_ui -.->|"submits message"| node_api
node_api -->|"gets reply"| node_chatbot
node_api -.->|"validates exchange"| node_models
node_chatbot -->|"normalizes and shortcuts"| node_rules
node_chatbot -->|"searches questions"| node_semantic
node_chatbot -->|"loads Q&amp;A"| node_dataset
node_chatbot -->|"reads thresholds"| node_config
node_chatbot -->|"requests generation"| node_ollama_client
node_ollama_client -.->|"calls API"| node_ollama

click node_ui "https://github.com/gokkul-ks/placebot/blob/main/static/index.html"
click node_api "https://github.com/gokkul-ks/placebot/blob/main/main.py"
click node_models "https://github.com/gokkul-ks/placebot/blob/main/schemas.py"
click node_chatbot "https://github.com/gokkul-ks/placebot/blob/main/chatbot.py"
click node_rules "https://github.com/gokkul-ks/placebot/blob/main/text_utils.py"
click node_semantic "https://github.com/gokkul-ks/placebot/blob/main/chatbot.py"
click node_dataset "https://github.com/gokkul-ks/placebot/blob/main/data.csv"
click node_config "https://github.com/gokkul-ks/placebot/blob/main/config.py"
click node_ollama_client "https://github.com/gokkul-ks/placebot/blob/main/ollama_client.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_ui,node_api,node_models,node_user toneBlue
class node_chatbot,node_rules toneAmber
class node_semantic,node_dataset toneMint
class node_config,node_ollama_client toneRose
class node_ollama toneIndigo
```

## Components

### Chat Experience

- [Chat UI](https://github.com/gokkul-ks/placebot/blob/main/static/index.html): `static/index.html`
- [FastAPI service](https://github.com/gokkul-ks/placebot/blob/main/main.py): `main.py`
- [API models](https://github.com/gokkul-ks/placebot/blob/main/schemas.py): `schemas.py`

### Response Engine

- [Response router](https://github.com/gokkul-ks/placebot/blob/main/chatbot.py): `chatbot.py`
- [Text rules](https://github.com/gokkul-ks/placebot/blob/main/text_utils.py): `text_utils.py`

### Knowledge Search

- [Semantic matching](https://github.com/gokkul-ks/placebot/blob/main/chatbot.py): `chatbot.py`
- [Placement Q&A](https://github.com/gokkul-ks/placebot/blob/main/data.csv): `data.csv`

### Configuration & Integrations

- [Settings](https://github.com/gokkul-ks/placebot/blob/main/config.py): `config.py`
- [Ollama client](https://github.com/gokkul-ks/placebot/blob/main/ollama_client.py): `ollama_client.py`

### Other components

- **Chat user**
- **Ollama service**

## Connections

- Chat user → Chat UI: asks (evidence: `README.md`)
- Chat UI → FastAPI service: submits message
- FastAPI service → Response router: gets reply (evidence: `README.md`)
- FastAPI service → API models: validates exchange
- Response router → Text rules: normalizes and shortcuts (evidence: `chatbot.py`)
- Response router → Semantic matching: searches questions (evidence: `chatbot.py`)
- Response router → Placement Q&A: loads Q&A (evidence: `README.md`)
- Response router → Settings: reads thresholds (evidence: `chatbot.py`)
- Response router → Ollama client: requests generation (evidence: `chatbot.py`)
- Ollama client → Ollama service: calls API
