# shiiinooo/thesis-code architecture

> Architecture diagram of the GitHub repository shiiinooo/thesis-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shiiinooo/thesis-code
- Repository: https://github.com/shiiinooo/thesis-code

## Overview

##### Project type and purpose
- This is a research-oriented multi-service codebase (“Thesis Code”) that demonstrates and evaluates three different search/QA approaches:
- Agentic (Node.js/TypeScript)
- Retrieval-Augmented Generation (RAG) (Python)
- Semantic Search (Python)
- A small Python “front” runner drives experiments, and there is a shared utility library plus a PostgreSQL database and external LLM API (e.g., OpenAI).

##### File structure
- Top-level:
- back/agentic – TS microservice with its own server.ts, DB schema (Drizzle + PostgreSQL), LLM providers, LangGraph tools
- back/rag – Python scripts using a RAG approach (backend.py, rag-based-approach.py)
- back/semantic – Python scripts for semantic embedding, search, indexing
- front/front.py – lightweight runner/UI that invokes each backend approach
- lib/ – shared Python/TS utilities (db_utils, llm_providers)
- one-for-all.py – likely an orchestrator that ties everything together
- test/ – evaluation scripts, test queries, test outputs
- Config/deployment files:
- .env.example – env vars (DATABASE_URL, OPENAI_API_KEY)
- back/agentic/package.json + tsconfig.json, Python requirements.txt in rag & semantic

##### README for additional insights
- Confirms split by approach in back/
- front/ is a small UI/runner
- test/ holds evaluation code and result plots
- Environment variables: database connection, OpenAI key

1. Front-end Runner (front/front.py or one-for-all.py)
2. Agentic Service (back/agentic)
3. RAG Scripts (back/rag)
4. Semantic Search Scripts (back/semantic)
5. Shared Utilities Library (lib/)
6. PostgreSQL Database (back/agentic/db + used by other services)
7. External LLM Provider (OpenAI API)
8. Test Harness & Reporting (test/) – optional side component
b. Relationships and interactions
1. Front Runner invokes each backend approach (Agentic, RAG, Semantic) in sequence or parallel.
2. Each backend:
- Reads/writes to PostgreSQL (e.g., Agentic uses Drizzle ORM; semantic uses index_embeddings.py; RAG may cache embeddings/search results).
- Calls the OpenAI API (via shared llm_providers module) or other LLM providers to generate or embed text.
- Returns results back to the front runner.
3. Front Runner collects results, passes them into test harness or evaluation scripts.
4. Test Harness reads test queries from test/data and writes test outputs/results in test/test_outputs.
c. Architectural patterns or design principles
- Micro-service–like separation: each approach lives in its own backend folder with its own runtime (Node vs. Python).
- Shared code extraction: lib/ provides common DB and LLM interfaces.
- Data-flow-driven evaluation: front runner orchestrates data flows through each service.
- Clear separation of concerns: indexing, searching, agent orchestration isolated per approach.
d. Key technologies/frameworks
- Node.js + TypeScript + Drizzle ORM (Agentic)
- Python + requirements.txt (RAG & Semantic)
- PostgreSQL (DATABASE_URL)
- OpenAI (OPENAI_API_KEY)
- Bun lockfile (back/agentic/bun.lock)
- ESLint (back/agentic/eslint.config.mjs)

##### Key details to capture
- Environment variables dependency (.env) for DB and API keys
- Distinct runtimes (Node vs. Python)
- Shared utilities library usage
- Data flow from test inputs → Front Runner → Backends → DB & LLM → Results → Test Outputs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front Runner
    subgraph "Front Runner"
        front_py["front/front.py"]:::service
        one_all["one-for-all.py"]:::service
    end

    %% Backend Services
    subgraph "Backend Services"
        Agentic["Agentic Service (Node/TS)"]:::service
        RAG["RAG Scripts (Python)"]:::service
        Semantic["Semantic Search (Python)"]:::service
    end

    %% Shared Utilities, Database, External API
    SharedUtil["Shared Utilities (lib/)"]:::util
    DB["PostgreSQL Database"]:::db
    LLM["OpenAI API"]:::api

    %% Test Harness
    subgraph "Test Harness & Reporting"
        TestHarness["Test Harness"]:::test
        Data["test/data"]:::test
        Outputs["test/test_outputs"]:::test
    end

    %% Relationships
    front_py -->|invokes| Agentic
    front_py -->|invokes| RAG
    front_py -->|invokes| Semantic
    one_all -->|invokes| Agentic
    one_all -->|invokes| RAG
    one_all -->|invokes| Semantic

    Agentic -->|uses| SharedUtil
    RAG -->|uses| SharedUtil
    Semantic -->|uses| SharedUtil

    Agentic -->|reads\u002Fwrites| DB
    RAG -->|reads\u002Fwrites| DB
    Semantic -->|reads\u002Fwrites| DB

    Agentic -->|calls| LLM
    RAG -->|calls| LLM
    Semantic -->|calls| LLM

    front_py -->|collects results| TestHarness
    one_all -->|collects results| TestHarness
    TestHarness -->|reads| Data
    TestHarness -->|writes| Outputs

    %% Click Events for Front Runner
    click front_py "https://github.com/shiiinooo/thesis-code/blob/main/front/front.py"
    click one_all "https://github.com/shiiinooo/thesis-code/blob/main/one-for-all.py"

    %% Click Events for Agentic Service
    click Agentic "https://github.com/shiiinooo/thesis-code/tree/main/back/agentic/"
    click server_ts "https://github.com/shiiinooo/thesis-code/blob/main/back/agentic/server.ts"
    click index_ts "https://github.com/shiiinooo/thesis-code/blob/main/back/agentic/index.ts"
    click utils_ts "https://github.com/shiiinooo/thesis-code/blob/main/back/agentic/utils.ts"
    click graph_ts "https://github.com/shiiinooo/thesis-code/blob/main/back/agentic/langgraph/graph.ts"
    click db_search_tool "https://github.com/shiiinooo/thesis-code/blob/main/back/agentic/langgraph/tools/db-search-tool.ts"
    click agentic_llm "https://github.com/shiiinooo/thesis-code/blob/main/back/agentic/lib/llm-providers.ts"
    click schema_ts "https://github.com/shiiinooo/thesis-code/blob/main/back/agentic/db/schema.ts"
    click drizzle_ts "https://github.com/shiiinooo/thesis-code/blob/main/back/agentic/db/drizzle.ts"
    click pkg_json "https://github.com/shiiinooo/thesis-code/blob/main/back/agentic/package.json"
    click tsconfig "https://github.com/shiiinooo/thesis-code/blob/main/back/agentic/tsconfig.json"

    %% Click Events for RAG Scripts
    click rag_backend "https://github.com/shiiinooo/thesis-code/blob/main/back/rag/backend.py"
    click rag_approach "https://github.com/shiiinooo/thesis-code/blob/main/back/rag/rag-based-approach.py"
    click rag_req "https://github.com/shiiinooo/thesis-code/blob/main/back/rag/requirements.txt"

    %% Click Events for Semantic Search
    click sem_index "https://github.com/shiiinooo/thesis-code/blob/main/back/semantic/index_embeddings.py"
    click sem_search "https://github.com/shiiinooo/thesis-code/blob/main/back/semantic/search.py"
    click sem_db_utils "https://github.com/shiiinooo/thesis-code/blob/main/back/semantic/db_utils.py"
    click sem_req "https://github.com/shiiinooo/thesis-code/blob/main/back/semantic/requirements.txt"

    %% Click Events for Shared Utilities
    click lib_db_utils "https://github.com/shiiinooo/thesis-code/blob/main/lib/db_utils.py"
    click lib_llm_providers "https://github.com/shiiinooo/thesis-code/blob/main/lib/llm_providers.py"

    %% Click Events for Test Harness
    click test_data "https://github.com/shiiinooo/thesis-code/tree/main/test/data"
    click test_outputs "https://github.com/shiiinooo/thesis-code/tree/main/test/test_outputs"
    click agentic_eval "https://github.com/shiiinooo/thesis-code/blob/main/test/agentic_eval_20.py"
    click rag_eval "https://github.com/shiiinooo/thesis-code/blob/main/test/rag_eval_20.py"
    click almighty "https://github.com/shiiinooo/thesis-code/blob/main/test/all-mighty.py"
    click explore_queries "https://github.com/shiiinooo/thesis-code/blob/main/test/explore_test_queries.py"
    click prepare_test "https://github.com/shiiinooo/thesis-code/blob/main/test/prepare-test-set.py"
    click test_models "https://github.com/shiiinooo/thesis-code/blob/main/test/test_models.py"
    click test_openai "https://github.com/shiiinooo/thesis-code/blob/main/test/test_openai_api.py"
    click check_db "https://github.com/shiiinooo/thesis-code/blob/main/test/check_database.py"
    click agentic_report "https://github.com/shiiinooo/thesis-code/blob/main/test/agentic_test_report.txt"
    click summary_report "https://github.com/shiiinooo/thesis-code/blob/main/test/test_summary_report.txt"

    %% Styles
    classDef service fill:#D6EAF8,stroke:#1B4F72,color:#1B2631,stroke-width:1px;
    classDef db fill:#D5F5E3,stroke:#145A32,color:#1B2631,stroke-width:1px;
    classDef api fill:#FADBD8,stroke:#7B241C,color:#1B2631,stroke-width:1px,stroke-dasharray: 5 5;
    classDef util fill:#FCF3CF,stroke:#7D6608,color:#1B2631,stroke-width:1px;
    classDef test fill:#E5E7E9,stroke:#566573,color:#1B2631,stroke-width:1px;
```
