# iamnguyenvu/airline-service-assistant architecture

> Architecture diagram of the GitHub repository iamnguyenvu/airline-service-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iamnguyenvu/airline-service-assistant
- Repository: https://github.com/iamnguyenvu/airline-service-assistant

## Overview

##### Project type and purpose
- This is a full-stack, AI-powered “Airline Service Assistant” platform combining a Next.js frontend (React App Router) with a Spring Boot backend.
- Purpose: Provide flight search/advisory, policy Q&A and real-time analytics via an AI chat interface, integrating LLM tool-calling, vector search (RAG), scheduled ingestion, and caching.

##### File structure
- Top level:
- backend/ (Spring Boot microservice)
- frontend/ (Next.js 16 App Router)
- docker-compose.yml (local orchestration)
- docs/ (architecture, deployment, development guides)
- backend: layered into ai/, flight/, policy/, user/, config/ and uses Flyway migrations, Redis cache, and REST controllers.
- frontend: organized into app/ pages, components/, lib/api client, hooks (React), public assets.
- CI/CD: .github/workflows for backend, frontend, Docker publishing.
- Docker Compose brings up PostgreSQL (with pgvector), Redis, Ollama (local LLM) plus services.

##### README for additional insights
- Articulates a modular architecture: AI Orchestrator + domain-specific tools (Flight, Policy).
- Core technologies: Java 21 + Spring Boot, Spring AI, Next.js, Tailwind & shadcn/ui, pgvector, Redis, Gemini API/Ollama.

##### Elements
- Frontend (blue)
- Backend core (green)
- Data stores (orange)
- AI engines (purple)
- External services (gray)
- Annotations for ports and tech (e.g., “Next.js (3000)”, “Spring Boot (8080)”, “PostgreSQL+pgvector (5432)”).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        UI["Next.js UI (3000)"]:::frontend
        Components["UI Components"]:::frontend
        APIClient["API Client"]:::frontend
        SupabaseClient["Supabase Integration"]:::frontend
        Hooks["Hooks (TanStack Query)"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        BackendApp["Spring Boot API (8080)"]:::backend
        subgraph Controllers
            direction TB
            ChatCtrl["ChatController"]:::backend
            FlightCtrl["Flight Controllers"]:::backend
            PolicyCtrl["PolicyController"]:::backend
        end
        subgraph Services
            direction TB
            Orchestrator["AiOrchestratorService"]:::backend
            ToolReg["ToolRegistry"]:::backend
            FlightSvc["Flight Services"]:::backend
            PolicySvc["Policy Services"]:::backend
        end
        subgraph Repositories
            direction TB
            FlightRepo["Flight Repositories"]:::backend
            PolicyRepo["Policy Repositories"]:::backend
            UserEntity["User Entities"]:::backend
        end
        subgraph Config
            direction TB
            Configs["Configuration"]:::backend
            Migrations["Flyway Migrations"]:::backend
            ServiceRules["Service Rules & Docs"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres["PostgreSQL + pgvector (5432)"]:::datastore
        Redis["Redis Cache (6379)"]:::datastore
    end

    %% External Layer
    subgraph "External Layer"
        direction TB
        Gemini["Gemini API"]:::ai
        Ollama["Ollama LLM (11434)"]:::ai
        FlightAPIs["Amadeus/Aviationstack"]:::external
        SupabaseExt["Supabase Auth & Storage"]:::external
        CI_CD["GitHub Actions"]:::external
    end

    %% Orchestration
    DockerCompose["Docker Compose"]:::external

    %% Connections
    UI -->|"HTTPS" | BackendApp
    Components --> UI
    APIClient --> UI
    SupabaseClient --> UI
    Hooks --> UI

    BackendApp -->|"/api/chat"| ChatCtrl
    BackendApp -->|"/api/flight"| FlightCtrl
    BackendApp -->|"/api/policy"| PolicyCtrl
    BackendApp -->|uses| Configs
    BackendApp -->|runs| Migrations
    BackendApp -->|loads| ServiceRules

    ChatCtrl -->|calls| Orchestrator
    Orchestrator -->|uses| ToolReg
    ToolReg -->|manages| FlightSvc
    ToolReg -->|manages| PolicySvc

    FlightCtrl -->|calls| FlightSvc
    FlightSvc -->|repo| FlightRepo
    FlightSvc -->|cache| Redis
    FlightSvc -->|ingest->| FlightAPIs

    PolicyCtrl -->|calls| PolicySvc
    PolicySvc -->|repo| PolicyRepo
    PolicySvc -->|cache| Redis
    PolicySvc -->|ingest->| ServiceRules

    Orchestrator -->|LLM RPC| Gemini
    Orchestrator -->|LLM RPC| Ollama

    BackendApp -->|JPA| Postgres
    Migrations -->|SQL| Postgres
    ServiceRules -->|files| Postgres
    UserEntity -->|repo| Postgres

    SupabaseClient -->|REST| SupabaseExt
    UI -->|auth| SupabaseExt

    DockerCompose --> BackendApp
    DockerCompose --> UI
    DockerCompose --> Postgres
    DockerCompose --> Redis
    DockerCompose --> Ollama

    CI_CD --> DockerCompose

    %% Click Events - Frontend
    click UI "https://github.com/iamnguyenvu/airline-service-assistant/tree/main/frontend/src/app"
    click Components "https://github.com/iamnguyenvu/airline-service-assistant/tree/main/frontend/src/components"
    click APIClient "https://github.com/iamnguyenvu/airline-service-assistant/blob/main/frontend/src/lib/api/client.ts"
    click SupabaseClient "https://github.com/iamnguyenvu/airline-service-assistant/blob/main/frontend/src/lib/supabase.ts"
    click Hooks "https://github.com/iamnguyenvu/airline-service-assistant/blob/main/frontend/src/hooks/use-toast.ts"

    %% Click Events - Backend
    click BackendApp "https://github.com/iamnguyenvu/airline-service-assistant/blob/main/backend/src/main/java/io/github/nguyenvu/backend/BackendApplication.java"
    click Orchestrator "https://github.com/iamnguyenvu/airline-service-assistant/blob/main/backend/src/main/java/io/github/nguyenvu/backend/ai/service/AiOrchestratorService.java"
    click ToolReg "https://github.com/iamnguyenvu/airline-service-assistant/blob/main/backend/src/main/java/io/github/nguyenvu/backend/ai/service/ToolRegistry.java"
    click ChatCtrl "https://github.com/iamnguyenvu/airline-service-assistant/blob/main/backend/src/main/java/io/github/nguyenvu/backend/ai/controller/ChatController.java"
    click FlightCtrl "https://github.com/iamnguyenvu/airline-service-assistant/tree/main/backend/src/main/java/io/github/nguyenvu/backend/flight/controller"
    click FlightSvc "https://github.com/iamnguyenvu/airline-service-assistant/tree/main/backend/src/main/java/io/github/nguyenvu/backend/flight/service"
    click FlightRepo "https://github.com/iamnguyenvu/airline-service-assistant/tree/main/backend/src/main/java/io/github/nguyenvu/backend/flight/repository"
    click PolicyCtrl "https://github.com/iamnguyenvu/airline-service-assistant/blob/main/backend/src/main/java/io/github/nguyenvu/backend/policy/controller/PolicyController.java"
    click PolicySvc "https://github.com/iamnguyenvu/airline-service-assistant/tree/main/backend/src/main/java/io/github/nguyenvu/backend/policy/service"
    click PolicyRepo "https://github.com/iamnguyenvu/airline-service-assistant/tree/main/backend/src/main/java/io/github/nguyenvu/backend/policy/repository"
    click UserEntity "https://github.com/iamnguyenvu/airline-service-assistant/tree/main/backend/src/main/java/io/github/nguyenvu/backend/user/entity"
    click Configs "https://github.com/iamnguyenvu/airline-service-assistant/tree/main/backend/src/main/java/io/github/nguyenvu/backend/config"
    click Migrations "https://github.com/iamnguyenvu/airline-service-assistant/tree/main/backend/src/main/resources/db/migration"
    click ServiceRules "https://github.com/iamnguyenvu/airline-service-assistant/tree/main/backend/src/main/resources/service-rules"

    %% Click Events - Infra
    click DockerCompose "https://github.com/iamnguyenvu/airline-service-assistant/blob/main/docker-compose.yml"
    click CI_CD "https://github.com/iamnguyenvu/airline-service-assistant/blob/main/.github/workflows/backend.yml"
    click CI_CD "https://github.com/iamnguyenvu/airline-service-assistant/blob/main/.github/workflows/frontend.yml"
    click CI_CD "https://github.com/iamnguyenvu/airline-service-assistant/blob/main/.github/workflows/docker.yml"

    %% Styles
    classDef frontend fill:#c3dafe,stroke:#4c51bf,color:#1a202c
    classDef backend fill:#c6f6d5,stroke:#2f855a,color:#1a202c
    classDef datastore fill:#fefcbf,stroke:#d69e2e,color:#1a202c
    classDef ai fill:#d6bcfa,stroke:#9f7aea,color:#1a202c
    classDef external fill:#e2e8f0,stroke:#718096,color:#1a202c
```
