# simpnick6703/talentscout-hiring-ai-assistant architecture

> Architecture diagram of the GitHub repository simpnick6703/talentscout-hiring-ai-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/simpnick6703/talentscout-hiring-ai-assistant
- Repository: https://github.com/simpnick6703/talentscout-hiring-ai-assistant

## Overview

##### Project type and purpose
- This repository implements a full-stack conversational AI assistant (“TalentScout”) for conducting structured interviews, plus a separate “Interview Reader” tool for visualizing exported interviews.
- The main app is built with Streamlit (app.py) and Python modules that orchestrate LLM calls, data processing, and UI rendering. The interview reader is a lightweight Flask/Jinja app under `interview_reader/`.

##### File structure
- Root directory:
- `app.py` – Streamlit entry point and route definitions
- `chatbot.py` – Core interview flow logic and LLM prompt orchestration
- `config.py` – LLM provider settings, UI theme flags, question-flow parameters
- `data_handler.py` – JSON serialization, file I/O, export logic
- `utils.py` – Helper functions (e.g., timestamp formatting)
- `static/styles.css` – Global CSS for any custom UI theming
- `requirements.txt` – Python dependencies
- `.github/` – CI workflows and Dependabot settings
- `interview_reader/` sub-app:
- `simple_reader.py` – Flask application to serve JSON-backed interview views
- `templates/` – Jinja2 HTML templates (index, upload, conversation, view_interview)
- `README.md` and `requirements.txt` for the reader tool

##### Key insights from the README
- Backend: Python + Streamlit
- Frontend: Streamlit UI + static CSS
- AI Integration: OpenAI Python SDK (or LM Studio)
- Data store: File-based JSON exports
- Interview phases: greeting → data gathering → technical questions → wrap-up
- Interview Reader: separate app for browsing and analyzing JSON exports

a. Main components to represent:
- Candidate’s browser or user interface
- Streamlit server (app.py)
- Chatbot engine (chatbot.py)
- Configuration manager (config.py)
- Data handler and JSON storage (data_handler.py + file system)
- External LLM provider (OpenAI / LM Studio API)
- Interview Reader service (simple_reader.py + templates)
b. Relationships and data flow:
1. Browser ↔ Streamlit server: UI events and responses
2. Streamlit server → Chatbot engine: “next question” requests
3. Chatbot engine → LLM provider: API calls for message generation
4. Chatbot engine → Data handler: append conversation chunks, export JSON
5. Browser → Interview Reader: JSON upload or file browse
6. Interview Reader → Templates: render conversation history
c. Architectural patterns and design principles:
– Separation of concerns: UI layer (Streamlit) vs. business logic (chatbot.py) vs. persistence (data_handler.py)
– Modular configuration (config.py) decouples environment and model settings
– MVC-style pattern in `interview_reader` (Flask routes, templates, static assets)
– Provider-agnostic LLM integration via adapter in config/chatbot
d. Relevant technologies and frameworks:
– Streamlit for UI
– Flask + Jinja2 for reader tool
– OpenAI Python SDK (or compatible LM Studio client)
– JSON file system for interview persistence

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    Browser["Candidate Browser"]:::frontend
    Browser -->|HTTP Streamlit UI| StreamlitServer["Streamlit Server\n(app.py)"]:::backend

    %% Backend Layer
    StreamlitServer -->|"calls"| ChatbotEngine["Chatbot Engine\n(chatbot.py)"]:::backend
    StreamlitServer -->|"loads config"| ConfigManager["Configuration Manager\n(config.py)"]:::config
    StreamlitServer -->|"serves CSS"| StaticAssets["Static Assets\n(static/styles.css)"]:::assets

    ChatbotEngine -->|"LLM request\n(HTTP API)"| LLMProvider["LLM Provider\n(OpenAI / LM Studio)"]:::external
    ChatbotEngine -->|"appends data"| DataHandler["Data Handler\n(data_handler.py)"]:::backend
    ChatbotEngine -->|"uses utils"| Utils["Helper Utilities\n(utils.py)"]:::backend

    DataHandler -->|"writes JSON"| JSONStore[(JSON File Store)]:::datastore

    %% Interview Reader Subsystem
    Browser2["Reader UI\n(Upload JSON)"]:::frontend
    Browser2 -->|HTTP| ReaderService["Interview Reader Service\n(simple_reader.py)"]:::backend

    subgraph "Reader Templates"
        Index["index.html"]:::frontend
        Upload["upload.html"]:::frontend
        Conversation["conversation.html"]:::frontend
        ViewInterview["view_interview.html"]:::frontend
    end

    ReaderService -->|renders| Index
    ReaderService -->|renders| Upload
    ReaderService -->|renders| Conversation
    ReaderService -->|renders| ViewInterview
    ReaderService -->|reads| JSONStore

    %% Project Artifacts
    subgraph "Project Artifacts"
        ReqMain["requirements.txt"]:::config
        ReqReader["interview_reader/requirements.txt"]:::config
        CIWorkflows[".github/workflows/codeql.yml"]:::config
        Dependabot[".github/dependabot.yml"]:::config
    end

    %% Click Events
    click StreamlitServer "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/app.py"
    click ChatbotEngine "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/chatbot.py"
    click ConfigManager "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/config.py"
    click DataHandler "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/data_handler.py"
    click Utils "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/utils.py"
    click StaticAssets "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/static/styles.css"
    click ReaderService "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/interview_reader/simple_reader.py"
    click Index "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/interview_reader/templates/index.html"
    click Upload "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/interview_reader/templates/upload.html"
    click Conversation "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/interview_reader/templates/conversation.html"
    click ViewInterview "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/interview_reader/templates/view_interview.html"
    click ReqMain "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/requirements.txt"
    click ReqReader "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/interview_reader/requirements.txt"
    click CIWorkflows "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/.github/workflows/codeql.yml"
    click Dependabot "https://github.com/simpnick6703/talentscout-hiring-ai-assistant/blob/main/.github/dependabot.yml"

    %% Styles
    classDef frontend fill:#D6EFFF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#FFEFD6,stroke:#d66306,stroke-width:1px
    classDef datastore fill:#D6FFD6,stroke:#037F04,stroke-width:1px
    classDef external fill:#F0D6FF,stroke:#6E03D6,stroke-width:1px
    classDef config fill:#FFF4D6,stroke:#d69e03,stroke-width:1px
    classDef assets fill:#EDEDED,stroke:#666666,stroke-width:1px
```
