# phatnguyen6635/hcmai2025_baseline architecture

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

- Interactive diagram: https://gitdiagram.com/phatnguyen6635/hcmai2025_baseline
- Repository: https://github.com/phatnguyen6635/hcmai2025_baseline

## Overview

##### Project Type and Purpose
- This is a full-stack AI application using FastAPI as the backend API server, Streamlit as the frontend UI, with vector search (Milvus), document store (MongoDB), and object storage (MinIO).
- It ingests embeddings and keyframe metadata via migration scripts, exposes search and agent endpoints, and provides a GUI for users to query AI models and browse results.

##### File Structure Insights
- Top-level services:
- app/            ← FastAPI application
- gui/            ← Streamlit-based frontend
- migration/      ← one-off data import scripts
- Inside app/:
- router/         ← HTTP route definitions
- controller/     ← request-handling logic
- service/        ← business logic (model, search)
- repository/     ← data access (Milvus, Mongo)
- agent/          ← orchestration components
- core/           ← DI, settings, logging, lifespan
- schema/, models/← Pydantic models and data classes
- factory/, main.py← application bootstrapping

##### Key Components
- Frontend (Streamlit GUI)
- Backend (FastAPI server)
- HTTP Routes (router)
- Controllers
- Services (ModelService, SearchService, Agents)
- Repositories (MongoRepository, MilvusRepository)
- External Systems
- Milvus (vector index)
- MongoDB (metadata store)
- MinIO (object storage for images/frames)
- Migration Scripts (offline ingestion)

##### Component Relationships and Data Flow
- User interacts with Streamlit UI → sends HTTP requests to FastAPI.
- FastAPI router directs to appropriate Controller.
- Controller calls Service layer:
- SearchService:
– Generates vector embedding via ModelService
– Queries Milvus for nearest neighbors
– Fetches metadata from MongoDB
– Constructs response including MinIO URLs
- ModelService: wraps AI model inference (OpenCLIP, PyTorch).
- Agent: orchestrates multi-step tasks, calling SearchService or other subsystems.
- Repositories handle low-level API calls to Milvus, MongoDB.
- Migration scripts load data into Milvus and MongoDB outside normal runtime.

##### Architectural Patterns and Design Principles
- Layered architecture: presentation (UI), API (router/controller), business (service), data (repository).
- Dependency Injection via FastAPI’s dependencies and core/factory modules.
- Factory pattern for object creation (app/factory).
- Clear separation of concerns: no direct DB calls in controllers, all data access in repositories.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Streamlit["Streamlit UI"]:::ui
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        AgentAPI["Agent Routes"]:::api
        KeyframeAPI["Keyframe Routes"]:::api
        AgentController["Agent Controller"]:::controller
        QueryController["Query Controller"]:::controller
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        SearchService["SearchService"]:::service
        ModelService["ModelService"]:::service
        AgentOrchestrator["Agent Orchestrator"]:::service
    end

    %% Data Access Layer
    subgraph "Data Layer"
        direction TB
        BaseRepo["Base Repository"]:::repo
        MilvusRepository["MilvusRepository"]:::repo
        MongoRepository["MongoRepository"]:::repo
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        MilvusDB["Milvus"]:::external
        MongoDB["MongoDB"]:::external
        MinIO["MinIO"]:::external
    end

    %% Migration Scripts
    subgraph "Migration Scripts"
        direction TB
        EmbeddingMig["Embedding Migration"]:::migration
        KeyframeMig["Keyframe Migration"]:::migration
    end

    %% Core & Bootstrapping
    subgraph "Core & Bootstrapping"
        direction TB
        AppMain["FastAPI Entry (app/main.py)"]:::core
        Dependencies["Dependencies"]:::core
        Lifespan["Lifespan Hooks"]:::core
        Logger["Logger Config"]:::core
        Settings["Settings"]:::core
        Factory["Factory Module"]:::core
    end

    %% Flows
    Streamlit -->|HTTP| AgentAPI
    Streamlit -->|HTTP| KeyframeAPI

    AgentAPI -->|calls| AgentController
    KeyframeAPI -->|calls| QueryController

    AgentController -->|orchestrate| AgentOrchestrator
    QueryController -->|invoke| SearchService

    SearchService -->|get_vector| ModelService
    SearchService -->|search| MilvusRepository
    SearchService -->|find| MongoRepository
    SearchService -->|construct URLs| MinIO

    AgentOrchestrator -->|uses| SearchService

    MilvusRepository -->|SDK| MilvusDB
    MongoRepository -->|SDK| MongoDB

    EmbeddingMig -->|load embeddings| MilvusDB
    KeyframeMig -->|load metadata| MongoDB

    AppMain --> Dependencies
    AppMain --> Lifespan
    AppMain --> Logger
    AppMain --> Settings
    AppMain --> Factory

    %% Click Events
    click Streamlit "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/gui/main.py"
    click AppMain "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/main.py"
    click AgentAPI "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/router/agent_api.py"
    click KeyframeAPI "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/router/keyframe_api.py"
    click AgentController "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/controller/agent_controller.py"
    click QueryController "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/controller/query_controller.py"
    click ModelService "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/service/model_service.py"
    click SearchService "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/service/search_service.py"
    click MilvusRepository "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/repository/milvus.py"
    click MongoRepository "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/repository/mongo.py"
    click BaseRepo "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/common/repository/base.py"
    click AgentOrchestrator "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/agent/agent.py"
    click Dependencies "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/core/dependencies.py"
    click Lifespan "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/core/lifespan.py"
    click Logger "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/core/logger.py"
    click Settings "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/core/settings.py"
    click Factory "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/app/factory/factory.py"
    click EmbeddingMig "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/migration/embedding_migration.py"
    click KeyframeMig "https://github.com/phatnguyen6635/hcmai2025_baseline/blob/main/migration/keyframe_migration.py"

    %% Styles
    classDef ui fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef api fill:#d4f1f9,stroke:#333,stroke-width:1px
    classDef controller fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef service fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef repo fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef external fill:#e1bee7,stroke:#333,stroke-width:1px
    classDef migration fill:#fff9c4,stroke:#333,stroke-width:1px
    classDef core fill:#f0f4c3,stroke:#333,stroke-width:1px
```
