How aivietnam-hub/hcmai2025_baseline works
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)