# melissa-ng/groupe_capstone architecture

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

- Interactive diagram: https://gitdiagram.com/melissa-ng/groupe_capstone
- Repository: https://github.com/melissa-ng/groupe_capstone

## Overview

##### Project Type and Purpose
- This is a full-stack web application that analyzes emergency medical call transcripts for protocol adherence.
- Front-end: React (Vite) single-page application, handles user sign-in (Google OAuth), transcript upload, results display, and history.
- Back-end: Python service exposing RESTful endpoints for parsing, vectorizing, and analyzing transcripts against dispatcher training material.
- Data layer: JSON-based vector stores (embeddings, document store, graph store, index store) and CSV source data.

##### File Structure
- Top level
- backend/ – core Python modules, data stores, schema models, an API entrypoint (api.py)
- frontend/ – React app (pages, components, static assets, configuration)
- unitTests/ – JavaScript, C++, and Python unit/integration tests for transcript parsing
- backend/data/db_indexing/ – prebuilt vector stores in JSON format
- backend/schema/models.py – data models (ORM or Pydantic)
- backend/EMS_CallAnalyzer.py & TranscriptExtractQ.py – NLP pipelines for transcript parsing and RAG comparison
- frontend/src/api.js – front-end HTTP client for calling backend endpoints
- frontend/src/pages/SignInPage/GoogleAuth.js – Google OAuth integration

##### README for Insights
- Uses OpenAI API for embedding (“vectorizing”) training material and caller transcripts.
- Employs a Retrieval-Augmented Generation (RAG) workflow.
- Core features: transcript parsing, timestamp extraction, question/response segmentation, error handling.
- Future scripts (vectorize.py, analyze_transcripts.py) live under scripts/ in the README’s dqa/ layout (not present in this tree but implied).

##### Main Components
a. User & Browser
- Google‐authenticated user interacts with the React UI.
b. Front-end (React/Vite)
- UI Pages: SignIn, TranscriptUpload, Results, History, Dispatchers.
- Communicates with the back-end over HTTPS.
c. Back-end Service (Python)
- API Layer (api.py) – defines REST endpoints: /upload, /analyze, /history, /vectorize.
- Processing Modules:
– TranscriptExtractQ.py – cleans and structures transcript text.
– EMS_CallAnalyzer.py – applies NLP, calls OpenAI embeddings and RAG to compare against training protocols.
d. Data Store
- CSV source: EMS-Calltaking-QA.csv.
- JSON vector stores: default__vector_store.json, image__vector_store.json, docstore.json, graph_store.json, index_store.json.
e. External Services
- OpenAI API – embeddings and RAG service.
- Google OAuth – for user authentication.
f. Dev & Test
- UnitTests in multiple languages verifying parsing modules and front-end components.
- Build tools: npm (frontend), Python 3.11 environment.

##### Relationships and Data Flows
- User → Front-end UI: uploads transcript, requests analysis, views results.
- Front-end → Back-end API: HTTP POST /uploadTranscript, GET /results.
- Back-end API → Processing Modules: invokes TranscriptExtractQ, EMS_CallAnalyzer.
- Processing Modules ↔ Data Store: read/write vector stores (JSON) and CSV.
- Processing Modules → OpenAI API: send text for embedding, RAG retrieval.
- Back-end → Front-end: returns JSON analysis payload (questions, answers, protocol adherence).
- Front-end → Google OAuth: handles sign-in, retrieves token.

##### Architectural Patterns and Design Principles
- Clear separation of concerns: UI, API, processing logic, and data storage.
- RESTful API boundary between front-end and back-end.
- Modular Python services (each module focuses on one responsibility).
- Retrieval-Augmented Generation (RAG) pattern for combining vector search with language models.
- File-based “vector store” as a simple, embeddable database for prototyping.

##### Essential Details to Capture
- All REST endpoints and the flow for “upload → parse → vectorize → analyze → return.”
- The data persistence format (JSON vector store) even if it’s not a traditional database.
- The integration points with OpenAI API and Google OAuth.
- Unit test suite as a supporting/micro component (optional, for completeness).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    User["Authenticated User"]:::user
    %% Presentation Layer
    subgraph "Frontend (React/Vite)" 
        direction TB
        ReactRoot["React App"]:::frontend
        APIClient["HTTP Client (api.js)"]:::frontend
        subgraph "Pages" 
            direction TB
            SignIn["SignInPage & GoogleAuth"]:::frontend
            Upload["TranscriptUploadPage"]:::frontend
            Results["ResultsPage"]:::frontend
            History["HistoryPage"]:::frontend
            Dispatchers["DispatchersPage"]:::frontend
        end
    end
    %% Application/Logic Layer
    subgraph "Backend Service (Python)" 
        direction TB
        APIServer["REST API (api.py)"]:::backend
        Models["Schema Models (models.py)"]:::backend
        Parser["Transcript Parser (TranscriptExtractQ.py)"]:::backend
        Analyzer["EMS Call Analyzer (EMS_CallAnalyzer.py)"]:::backend
    end
    %% Data Layer
    subgraph "Data Stores" 
        direction TB
        CSV["EMS-Calltaking-QA.csv"]:::data
        JSONStores["JSON Vector Stores"]:::data
    end
    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        GoogleAuthService["Google OAuth"]:::external
    end
    %% Dev & Test Layer
    subgraph "Unit Tests"
        direction TB
        JSTests["JS Unit Tests"]:::test
        PyTest["Python Unit Test"]:::test
        CppTest["C++ Unit Test"]:::test
    end

    %% Connections
    User -->|"uses"| ReactRoot
    ReactRoot -->|"calls"| APIClient
    ReactRoot -->|"auth via"| GoogleAuthService
    APIClient -->|"POST /uploadTranscript\nGET /results"| APIServer
    APIServer -->|"uses models"| Models
    APIServer -->|"invokes"| Parser
    APIServer -->|"invokes"| Analyzer
    Parser -->|"reads/writes"| CSV
    Analyzer -->|"reads/writes"| JSONStores
    Analyzer -->|"embeds & retrieves"| OpenAI
    APIServer -->|"returns JSON"| APIClient
    APIClient -->|"updates UI"| SignIn
    APIClient -->|"updates UI"| Upload
    APIClient -->|"updates UI"| Results
    APIClient -->|"updates UI"| History
    APIClient -->|"updates UI"| Dispatchers
    JSTests --> ReactRoot
    JSTests --> Parser
    PyTest --> Parser
    CppTest --> Parser

    %% Click events
    click ReactRoot "https://github.com/melissa-ng/groupe_capstone/tree/main/frontend/"
    click APIClient "https://github.com/melissa-ng/groupe_capstone/blob/main/frontend/src/api.js"
    click SignIn "https://github.com/melissa-ng/groupe_capstone/tree/main/frontend/src/pages/SignInPage/"
    click Upload "https://github.com/melissa-ng/groupe_capstone/tree/main/frontend/src/pages/TranscriptUploadPage/"
    click Results "https://github.com/melissa-ng/groupe_capstone/tree/main/frontend/src/pages/ResultsPage/"
    click History "https://github.com/melissa-ng/groupe_capstone/tree/main/frontend/src/pages/HistoryPage/"
    click Dispatchers "https://github.com/melissa-ng/groupe_capstone/tree/main/frontend/src/pages/DispatchersPage/"
    click APIServer "https://github.com/melissa-ng/groupe_capstone/blob/main/backend/api.py"
    click Parser "https://github.com/melissa-ng/groupe_capstone/blob/main/backend/TranscriptExtractQ.py"
    click Analyzer "https://github.com/melissa-ng/groupe_capstone/blob/main/backend/EMS_CallAnalyzer.py"
    click Models "https://github.com/melissa-ng/groupe_capstone/blob/main/backend/schema/models.py"
    click CSV "https://github.com/melissa-ng/groupe_capstone/blob/main/backend/data/EMS-Calltaking-QA.csv"
    click JSONStores "https://github.com/melissa-ng/groupe_capstone/tree/main/backend/data/db_indexing/"
    click JSTests "https://github.com/melissa-ng/groupe_capstone/tree/main/unitTests/JsTest/"
    click PyTest "https://github.com/melissa-ng/groupe_capstone/blob/main/unitTests/pythonTextTranscriptUnitTest.py"
    click CppTest "https://github.com/melissa-ng/groupe_capstone/blob/main/unitTests/c++TextTranscriptUnitTest.cpp"

    %% Styles
    classDef user fill:#f0f8ff,stroke:#333,stroke-width:1px
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef data fill:#e2e3e5,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#d4edda,stroke:#333,stroke-width:1px
    classDef test fill:#f8d7da,stroke:#333,stroke-width:1px,stroke-dasharray: 2 2
```
