How phatnguyen6635/hcmai2025_baseline works
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.