# keyinglol/alibabahack2025 architecture

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

- Interactive diagram: https://gitdiagram.com/keyinglol/alibabahack2025
- Repository: https://github.com/keyinglol/alibabahack2025

## Overview

##### Project type and purpose
- This is a full-stack, cloud-powered inventory management system for F&B businesses.
- Frontend: an Angular single-page application delivering dashboards and chat-style “Smart Q” insights.
- Backend/pipeline: Python-based ML scripts (notebooks, pickled models, cron jobs) that forecast T+2 sales.
- Cloud services: Alibaba Cloud ECS for compute, PAI DSW for data processing, ApsaraDB RDS for storage, Quick BI & Smart Q for visualization and LLM analytics.

##### File structure
- Top level:
- `inventory-assistant-frontend/` – Angular project with `src/app` pages, shared components, services, models.
- `inventory-assistant-backend/` – Data science artifacts: Jupyter notebooks (`.ipynb`), CSV data, pickled model files (`.pkl`), and Python scripts (`predict_t_plus_2.py`).
- No monolithic REST server; instead, a scheduled Python script on ECS drives prediction and persists results.
- Configuration & build: `angular.json`, `package.json` in frontend; no backend build script implies pure script-based pipeline.

##### README for additional insights
- Confirms Angular.js UI with embedded Quick BI dashboards and Smart Q LLM queries.
- Describes data pipeline on PAI DSW: validation → feature engineering → cleaned data storage.
- Cron on ECS runs predictions daily, writes to ApsaraDB RDS.
- Frontend likely uses store.service.ts to embed or fetch BI/Smart Q endpoints.

##### Main components
a. User devices / Web browser
b. Angular frontend (hosted on ECS or CDN)
c. Alibaba Cloud Quick BI & Smart Q services (external BI & LLM)
d. Data storage: ApsaraDB RDS
e. Data pipeline: PAI DSW (validation & feature engineering)
f. Compute: Alibaba Cloud ECS running:
- Prediction cron job (`predict_t_plus_2.py`)
- Model artifacts (`sales_forecast_model.pkl`, `categorical_columns.pkl`)
g. Raw data sources (daily CSV uploads or ingested sales data)

##### Relationships and data flows
- Raw sales/inventory data → ingested into PAI DSW
- PAI DSW → cleans & transforms → writes to ApsaraDB RDS
- ECS cron → reads today’s data from RDS + loaded ML model → writes T+2 forecasts back to RDS
- Quick BI dashboards & Smart Q → read from RDS → serve visualizations and LLM analyses to Angular frontend
- End user → interacts with Angular app → triggers BI/Smart Q embed queries → views insights

##### Architectural patterns / design principles
- Clear separation of concerns:
- Frontend: presentation & user interaction
- Backend compute: ML pipeline & batch prediction
- Data layer: RDS for OLTP/analytics store
- Analytics services: managed PAI & Quick BI/Smart Q
- Batch processing via cron jobs; event-driven if extended with Lambda-style triggers.
- Modular ML artifacts for easy retraining and redeployment.
- Stateless frontend + external BI/LLM services minimize custom API load.

##### Technologies / frameworks to annotate
- Angular (Typescript, `store.service.ts`, `app.routes.ts`)
- Python (Jupyter notebooks, `predict_t_plus_2.py`, scikit-learn pickles)
- Alibaba Cloud ECS, PAI DSW, ApsaraDB RDS
- Alibaba Cloud Quick BI & Smart Q
- Data formats: CSV, pickled models

##### Final checklist for the engineer
- Break system into: frontend, batch compute, data store, analytics services, and user.
- Data flows and triggers (cron schedule).
- ML artifacts and notebooks as part of the pipeline.
- Hosting boundaries: ECS vs. PAI vs. SaaS.
- Essential components without over-complicating.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    User["End User"]:::user

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        AngularSPA["Angular SPA"]:::frontend
        AppConfig["app.config.ts"]:::frontend
        AppRoutes["app.routes.ts"]:::frontend
        Dashboard["Dashboard Component"]:::frontend
        ChatQ["Smart Q Component"]:::frontend
        StoreService["Store Service"]:::frontend
    end

    %% Analytics Services Layer
    subgraph "Analytics Services (SaaS)" 
        direction TB
        QuickBI["Quick BI"]:::saas
        SmartQ["Smart Q"]:::saas
    end

    %% Compute & Pipeline Layer
    subgraph "Compute & Pipeline"
        direction TB
        subgraph "PAI DSW (Validation & Feature Engineering)"
            direction TB
            Notebook1["convert_xlsx_to_csv.ipynb"]:::pipeline
            Notebook2["prediction.ipynb"]:::pipeline
        end
        subgraph "ECS (Cron Prediction Service)"
            direction TB
            PredictScript["predict_t_plus_2.py"]:::compute
            ModelArtifact["sales_forecast_model.pkl"]:::compute
            ColumnsArtifact["categorical_columns.pkl"]:::compute
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawData["Raw Sales CSV"]:::data
        RDS["ApsaraDB RDS"]:::data
    end

    %% Relationships
    RawData -->|"CSV upload"| Notebook1
    Notebook1 -->|"cleaned data"| Notebook2
    Notebook2 -->|"writes SQL"| RDS

    PredictScript -->|"reads/writes SQL"| RDS
    ModelArtifact -.->PredictScript
    ColumnsArtifact -.->PredictScript

    RDS -->|"SQL queries"| QuickBI
    RDS -->|"SQL queries"| SmartQ

    QuickBI -->|"embed/JSON"| StoreService
    SmartQ -->|"embed/JSON"| StoreService

    StoreService -->|"provides data to"| Dashboard
    StoreService -->|"provides data to"| ChatQ

    User -->|"interacts with"| AngularSPA
    AngularSPA -->|"uses"| StoreService
    AngularSPA -->|"configured by"| AppConfig
    AngularSPA -->|"routes via"| AppRoutes
    AngularSPA -->|"renders"| Dashboard
    AngularSPA -->|"renders"| ChatQ

    %% Click Events
    click AngularSPA "https://github.com/keyinglol/alibabahack2025/tree/master/inventory-assistant-frontend/"
    click AppConfig "https://github.com/keyinglol/alibabahack2025/blob/master/inventory-assistant-frontend/src/app/app.config.ts"
    click AppRoutes "https://github.com/keyinglol/alibabahack2025/blob/master/inventory-assistant-frontend/src/app/app.routes.ts"
    click Dashboard "https://github.com/keyinglol/alibabahack2025/blob/master/inventory-assistant-frontend/src/app/pages/dashboard/dashboard.component.ts"
    click ChatQ "https://github.com/keyinglol/alibabahack2025/blob/master/inventory-assistant-frontend/src/app/pages/chat-box/chat-box.component.ts"
    click StoreService "https://github.com/keyinglol/alibabahack2025/blob/master/inventory-assistant-frontend/src/services/store.service.ts"
    click Notebook1 "https://github.com/keyinglol/alibabahack2025/blob/master/inventory-assistant-backend/convert_xlsx_to_csv.ipynb"
    click Notebook2 "https://github.com/keyinglol/alibabahack2025/blob/master/inventory-assistant-backend/prediction.ipynb"
    click PredictScript "https://github.com/keyinglol/alibabahack2025/blob/master/inventory-assistant-backend/predict_t_plus_2.py"
    click ModelArtifact "https://github.com/keyinglol/alibabahack2025/blob/master/inventory-assistant-backend/sales_forecast_model.pkl"
    click ColumnsArtifact "https://github.com/keyinglol/alibabahack2025/blob/master/inventory-assistant-backend/categorical_columns.pkl"
    click RawData "https://github.com/keyinglol/alibabahack2025/blob/master/inventory-assistant-backend/coffee_shop_sales.csv"
    click README "https://github.com/keyinglol/alibabahack2025/blob/master/README.md"

    %% Styles
    classDef user fill:#eeeeee,stroke:#999,stroke-width:1px;
    classDef frontend fill:#cce5ff,stroke:#339,stroke-width:1px;
    classDef saas fill:#e5ccff,stroke:#933,stroke-width:1px;
    classDef pipeline fill:#ccffcc,stroke:#393,stroke-width:1px;
    classDef compute fill:#b3e6b3,stroke:#2d7,stroke-width:1px;
    classDef data fill:#ffe5b3,stroke:#e68a00,stroke-width:1px;
```
