# lengvietcuong/examinai architecture

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

- Interactive diagram: https://gitdiagram.com/lengvietcuong/examinai
- Repository: https://github.com/lengvietcuong/examinai

## Overview

##### Main Project Components
- Frontend (Next.js Application)
- The “app” directory shows Next.js’s file-based routing with files like layout.tsx and page.tsx.
- Different UI sections such as the header, sidebar, and chat interface are implemented in the “components” folder.
- Chat Module
- Under “components/chat”, there are several subcomponents for conversations, greetings, messages, and user inputs.
- Components to show the chat’s structure (conversation handling, scoring, corrections, etc.).
- Header and Sidebar UI
- The “components/header” folder contains items for control and profile areas, while “components/sidebar” has UI for conversation history and chat controls.
- Shared UI and Utility Components
- The “components/ui” directory contains reusable UI components (buttons, dialogs, dropdowns) that maintain a consistent look and feel.
- External Integrations / Libraries
- The “lib” folder includes integrations with external services like Deepgram (likely for speech processing) and Firebase (for authentication or data storage).
- The “public” folder holds JSON files with band descriptors and speaking questions that likely drive the examiner’s feedback.
- State Management
- The “stores” directory indicates the use of global state management (e.g., conversationStore, examinerStateStore) to coordinate UI state across components.
- Utility Functions and Types
- The “utils” folder holds helper functions for essay submission, prompt extraction, streaming responses, etc.
- Custom TypeScript types are maintained in the “types” folder.

##### Relationships and Interactions
- The User Interface (frontend) consists of interrelated components where:
- The Header shows user-related actions (sign in, profile details).
- The Sidebar provides navigation for conversation history and initiating new chats.
- The Chat interface (with its subcomponents) handles user interaction, message display, correction feedback, and suggestions.
- State Management:
- The various “stores” modules interact with UI components to maintain a consistent conversation flow and examiner state.
- Backend / External Services:
- API calls and integrations (found under “lib”) facilitate features like real-time speech-to-text (Deepgram) and storing sessions or user data (Firebase).
- Data Flow:
- User actions trigger frontend events that update state stores, and these can in turn invoke API functions from “lib” or utility functions in “utils” to process submissions or stream responses.

##### Architectural Patterns and Design Principles
- Component-Based Design:
- The clear separation of concerns with modular React components (organized by feature domains such as chat, header, sidebar, etc.) follows a component-based design strategy.
- Separation of UI and Logic:
- Business logic and side effects are abstracted into utilities, libraries, and state management stores, keeping the UI components focused mainly on rendering.
- Integration with External APIs:
- The code structure supports external integrations (Deepgram and Firebase) which are decoupled from the UI, suggesting the use of service layer abstraction.
- Next.js Conventions:
- Use of file-based routing and global CSS within the “app” folder implies adherence to Next.js architectural norms.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client (Frontend) Layer
    subgraph "Client (Frontend) Layer"
        NextJSApp["Next.js Application"]:::project
        Chat["Chat Module\n(Conversations, Greetings, Messages, User Inputs)"]:::ui
        Header["Header UI"]:::ui
        Sidebar["Sidebar UI"]:::ui
        SharedUI["Shared UI Components"]:::ui
    end

    %% State Management Layer
    subgraph "State Management Layer"
        StateMgmt["State Management\n(Stores: conversationStore, examinerStateStore, etc.)"]:::state
    end

    %% External Integration Layer
    subgraph "External Integration Layer"
        ExtIntegrations["External Integrations\n(Deepgram, Firebase)"]:::integration
    end

    %% Utility & Data Layer
    subgraph "Utility & Data Layer"
        UtilityFns["Utility Functions"]:::utility
        Types["Custom Types"]:::utility
        PublicData["Public Data Files"]:::data
    end

    %% Connections within UI Layer
    NextJSApp -->|"routesTo"| Chat
    NextJSApp -->|"routesTo"| Header
    NextJSApp -->|"routesTo"| Sidebar
    NextJSApp -->|"routesTo"| SharedUI

    %% Connections between UI and State Management
    Chat -->|"updates"| StateMgmt
    Header -->|"triggers"| StateMgmt
    Sidebar -->|"navigates"| StateMgmt

    %% State Management to External Integrations and Utility Functions
    StateMgmt -->|"callsAPIs"| ExtIntegrations
    StateMgmt -->|"utilizes"| UtilityFns
    ExtIntegrations -->|"dataResponse"| StateMgmt

    %% Utility Layer internal connections
    UtilityFns -->|"defines"| Types
    UtilityFns -->|"supports"| PublicData

    %% Click Events
    click NextJSApp "https://github.com/lengvietcuong/examinai/tree/main/app/"
    click Chat "https://github.com/lengvietcuong/examinai/tree/main/components/chat/"
    click Header "https://github.com/lengvietcuong/examinai/tree/main/components/header/"
    click Sidebar "https://github.com/lengvietcuong/examinai/tree/main/components/sidebar/"
    click SharedUI "https://github.com/lengvietcuong/examinai/tree/main/components/ui/"
    click StateMgmt "https://github.com/lengvietcuong/examinai/tree/main/stores/"
    click ExtIntegrations "https://github.com/lengvietcuong/examinai/tree/main/lib/"
    click UtilityFns "https://github.com/lengvietcuong/examinai/tree/main/utils/"
    click Types "https://github.com/lengvietcuong/examinai/tree/main/types/"
    click PublicData "https://github.com/lengvietcuong/examinai/tree/main/public/"

    %% Styles
    classDef project fill:#B0C4DE,stroke:#000,stroke-width:1px;
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef state fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef integration fill:#FFA07A,stroke:#000,stroke-width:1px;
    classDef utility fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef data fill:#FFD700,stroke:#000,stroke-width:1px;
```
