# aivietnam-hub/hcmai2025_baseline architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack AI application with:
- A FastAPI backend exposing REST endpoints and orchestrating AI search/agent logic.
- A Streamlit GUI frontend for user interaction.
- Vector search via Milvus, metadata storage in MongoDB, and object storage with MinIO.

##### File structure
- Top-level directories:
- app/ – FastAPI service (controllers, routers, services, models, schemas, repository adapters)
- gui/ – Streamlit-based user interface
- migration/ – scripts to seed Milvus and MongoDB with embeddings and keyframes
- Key files:
- app/main.py – FastAPI app entrypoint
- app/router/*_api.py – HTTP routes
- app/controller/*_controller.py – Request handling & orchestration
- app/service/* – Business logic (model inference, vector search)
- app/repository/*.py – Adapters for Milvus and MongoDB
- app/core/* – Dependency injection, settings, logger, app lifespan
- app/agent – AI agent logic layer
- gui/main.py – Streamlit app that consumes FastAPI endpoints

##### Extract architectural clues from README
- Uses Docker Compose to spin up MongoDB, Milvus, MinIO
- Two separate UIs: one via Streamlit (gui/) and one via FastAPI’s own server
- Migration step populates data stores before runtime

##### Main components & interactions (
a. Components:
1. GUI (Streamlit client in gui/main.py)
2. API Layer (FastAPI app in app/main.py)
3. Controller/Router layer (app/router + app/controller)
4. Service layer:
- ModelService (inference, embed queries)
- SearchService (Milvus vector search)
- Agent (main_agent.py orchestrating complex workflows)
5. Repository layer:
- Milvus adapter (app/repository/milvus.py)
- MongoDB adapter (app/repository/mongo.py)
- MinIO usage (likely via HTTP calls or SDK)
6. Datastores:
- Milvus (vector store)
- MongoDB (metadata, keyframes)
- MinIO (raw image/keyframe blobs)
7. Migration Scripts (one-time data load)

b. Relationships/Data flows:
- GUI ←HTTP→ FastAPI Router → Controller → Service → Repository → Datastore
- Service may call both ModelService (for embeddings) and SearchService (for vector search)
- Agent module may call external LLM or orchestrate multi-step queries via ModelService/SearchService
- Migration scripts directly invoke repository adapters to seed data

c. Architectural patterns/design principles:
- Layered architecture (Router → Controller → Service → Repository)
- Dependency injection (app/core/dependencies.py)
- Factory pattern (app/factory/factory.py) for model/agent instantiation
- Clean separation of concerns (schemas for request/response, models for domain objects)

d. Key technologies/frameworks:
- FastAPI (HTTP framework)
- Pydantic (schemas, settings)
- Beanie/Motor (MongoDB ODM)
- pymilvus (Milvus client)
- Streamlit (GUI)
- Docker Compose (local infra orchestration)
- uv (project toolchain)

##### Detail
- External dependencies (LLM endpoints or other AI services if used)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        GUI["Streamlit GUI"]:::frontend
        HTTPClient["HTTP Client"]:::frontend
    end

    %% FastAPI Service
    subgraph "FastAPI Service" 
        direction TB
        API["FastAPI App (app/main.py)"]:::backend
        subgraph "Router Layer"
            direction TB
            AgentAPI["Agent Routes"]:::backend
            KeyframeAPI["Keyframe Routes"]:::backend
        end
        subgraph "Controller Layer"
            direction TB
            AgentController["Agent Controller"]:::backend
            QueryController["Query Controller"]:::backend
        end
        subgraph "Service Layer"
            direction TB
            ModelService["ModelService"]:::backend
            SearchService["SearchService"]:::backend
        end
        subgraph "Agent Logic"
            direction TB
            AgentCore["Agent"]:::backend
            MainAgent["MainAgent"]:::backend
        end
        subgraph "Repository Layer"
            direction TB
            MilvusAdapter["Milvus Adapter"]:::backend
            MongoAdapter["MongoDB Adapter"]:::backend
            BaseRepo["Base Repository"]:::backend
        end
        subgraph "Core Infrastructure"
            direction TB
            Dependencies["Dependencies"]:::infra
            Lifespan["Lifespan Hooks"]:::infra
            Logger["Logger Config"]:::infra
            Settings["Settings"]:::infra
        end
        Factory["Factory"]:::backend
        Models["Keyframe Model"]:::backend
        subgraph "Schemas"
            direction TB
            AgentSchema["agent.py"]:::backend
            InterfaceSchema["interface.py"]:::backend
            RequestSchema["request.py"]:::backend
            ResponseSchema["response.py"]:::backend
        end
    end

    %% Datastores & Infra
    subgraph "Datastores & Infra"
        direction TB
        MilvusDB["Milvus"]:::data
        MongoDB["MongoDB"]:::data
        MinIO["MinIO"]:::data
    end

    %% Migration Scripts
    subgraph "Migration Scripts"
        EmbeddingMig["embedding_migration.py"]:::infra
        KeyframeMig["keyframe_migration.py"]:::infra
    end

    %% Connections
    GUI -->|HTTP/REST| AgentAPI
    HTTPClient -->|HTTP/REST| AgentAPI
    API --> AgentAPI
    AgentAPI --> AgentController
    KeyframeAPI --> QueryController
    AgentController --> ModelService
    AgentController --> SearchService
    QueryController --> SearchService
    ModelService --> MilvusAdapter
    SearchService --> MilvusAdapter
    ModelService --> MongoAdapter
    SearchService --> MongoAdapter
    MilvusAdapter --> MilvusDB
    MongoAdapter --> MongoDB
    ModelService --> MinIO
    SearchService --> MinIO
    AgentController -->|uses| AgentCore
    AgentCore --> MainAgent
    AgentCore --> Factory
    Factory --> ModelService
    Factory --> AgentCore
    Dependencies --> API
    Lifespan --> API
    Logger --> API
    Settings --> API
    EmbeddingMig --> MilvusAdapter
    EmbeddingMig --> MongoAdapter
    KeyframeMig --> MilvusAdapter
    KeyframeMig --> MongoAdapter

    %% Click Events
    click GUI "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/gui/main.py"
    click API "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/main.py"
    click AgentAPI "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/router/agent_api.py"
    click KeyframeAPI "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/router/keyframe_api.py"
    click AgentController "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/controller/agent_controller.py"
    click QueryController "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/controller/query_controller.py"
    click ModelService "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/service/model_service.py"
    click SearchService "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/service/search_service.py"
    click AgentCore "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/agent/agent.py"
    click MainAgent "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/agent/main_agent.py"
    click MilvusAdapter "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/repository/milvus.py"
    click MongoAdapter "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/repository/mongo.py"
    click BaseRepo "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/common/repository/base.py"
    click Dependencies "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/core/dependencies.py"
    click Lifespan "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/core/lifespan.py"
    click Logger "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/core/logger.py"
    click Settings "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/core/settings.py"
    click Factory "https://github.com/aivietnam-hub/hcmai2025_baseline/blob/main/app/factory/factory.py"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#2980B9
    classDef backend fill:#D5F5E3,stroke:#27AE60
    classDef data fill:#EBDEF0,stroke:#8E44AD
    classDef infra fill:#D5DBDB,stroke:#7F8C8D
```
