# dcy0577/bim-command-recommendation architecture

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

- Interactive diagram: https://gitdiagram.com/dcy0577/bim-command-recommendation
- Repository: https://github.com/dcy0577/bim-command-recommendation

## Overview

##### Project type and purpose
- This is a full-stack predictive modeling system for BIM command recommendation. It spans data engineering (large-scale log processing), ML model development (training transformer-based recommenders), a custom modeling library (transformers4rec + peft), deployment (Triton server, local inference, ensemble scripts), and a real-time web prototype (FastAPI backend + Vue.js frontend).

##### File structure
- Top-level directories:
- data_processing – pipelines to filter and enrich raw BIM logs
- model – training, evaluation, and utility scripts built on your custom libraries
- deployment – scripts/templates to package, ensemble, and serve models (Triton, local)
- prototype – real-time service that watches logs and serves command suggestions via FastAPI + Vue.js
- transformers4rec & peft – the custom versions of Nvidia’s and Huggingface’s libraries you extend
- visualization – scripts to produce figures for analysis
- Config and orchestration: docker-compose.dev.deploy.yml, conda env yml, Triton config pbtxt
- MVC and micro-services elements: data pipelines are standalone scripts/notebooks; model code lives in its own folder; deployment is service-oriented; prototype is a two-tier (API + front end) app.

##### Extract additional insights from the README
- Data scale: 32 billion rows of global log data
- Model: transformer backbone + custom feature fusion + dedicated loss + learning strategy
- Deployment: Triton inference server, Python backend, ensemble of PEFT LLMs, local inference for testing
- Prototype: polls Vectorworks logs, returns “next command” suggestions in real time

a. Main components
1. Raw Data Ingestion: BIM logs (flat files / parquet)
2. Data Processing Pipelines: modules in data_processing that filter, group, cluster, augment, and remove redundancy
3. Feature Store / Preprocessed Data: artifacts written to disk or table format for training
4. Model Training & Evaluation: scripts in model/ that load data, build transformer-based model via transformers4rec + peft, run training, evaluate metrics
5. Model Repository: saved checkpoints (model.pt) and Triton model directory built with deploy_template
6. Deployment Services:
- Triton Inference Server (with Python backend & config.pbtxt)
- Local inference script for dev/testing
- Ensemble PEFT LLM script that wraps multiple model variants
7. Real-Time API Service: FastAPI endpoints (in prototype/web_application/fastapi)
8. Frontend Application: Vue.js SPA (in prototype/web_application/frontend)
9. Visualization Tools: standalone scripts to generate plots (not part of runtime)

b. Relationships and interactions
- Data flows from Raw Data → Data Processing → Preprocessed Data
- Preprocessed Data → Model Training → Checkpoints → Model Repository
- Model Repository → Deployment Scripts → Triton Server & Local Inference
- Triton & Local Inference Services → API Service
- API Service ↔ Frontend (user requests recommendation, receives next-command suggestions)
- Visualization reads Preprocessed Data or Model Outputs for offline analysis

c. Architectural patterns & design principles
- Modular pipeline: separate data processing notebooks/scripts by logical stages
- Library reuse: custom extensions (transformers4rec, peft) abstract low-level modeling details
- Service-oriented inference: Triton server for high throughput, local script for dev
- Microservice for real-time recommendations: decoupled FastAPI + SPA
- Configuration as code: conda yml, docker-compose, Triton config

d. Key technologies
- Python, Jupyter notebooks for data pipelines
- PyTorch (through transformers4rec), Huggingface PEFT for model training
- NVIDIA Triton Inference Server (Python backend)
- FastAPI for REST API
- Vue.js + Vite for frontend SPA
- Docker Compose for orchestration
- Conda for environment management

##### Checklist for the principal software engineer
- Clear, descriptive labels on every component
- External dependencies (e.g., Vectorworks logs, CUDA-enabled GPU)
- Essential subsystems: data_processing, model training, custom library, deployment, API, frontend
- If space allows, insert version or technology callouts (e.g., “Triton v2.x,” “Vue 3 / Vite”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Processing" 
        direction TB
        RawLogs["Raw BIM Logs\n(flat files/parquet)"]:::data
        Prefiltering["Prefiltering & GroupBy"]:::data
        LogProcessing["Command Augmentation\n& Workflow Generation"]:::data
        MultiLang["Multi-language Alignment"]:::data
        Redundancy["Redundant Command\nIdentification & Removal"]:::data
        PreprocessedData["Feature Store /\nPreprocessed Data"]:::data
    end

    %% Model Layer
    subgraph "Model Training & Evaluation"
        direction TB
        TrainBaseline["Train/Eval Baseline Models"]:::compute
        TrainFull["Train/Eval Full Models"]:::compute
        ModelUtils["Model Utils"]:::compute
        TextEmbed["Pretrained Text Embedding"]:::compute
    end

    subgraph "Custom Libraries"
        direction TB
        Transformers4Rec["Transformers4Rec Extensions"]:::compute
        PeftLib["PEFT Extensions"]:::compute
    end

    %% Model Repository & Deployment Templates
    subgraph "Model Repository & Templates"
        direction TB
        ModelRepo["Model Repository\n(checkpoints, Triton model dir)"]:::compute
        TritonConfig["Triton Config (pbtxt)"]:::compute
        DeployTemplate["Deployment Template\n(model.py)"]:::compute
    end

    %% Deployment Services
    subgraph "Deployment Services"
        direction TB
        TritonServer["Triton Inference Server"]:::serving
        LocalInfer["Local Inference Script"]:::serving
        EnsembleLLM["Ensemble PEFT LLM Script"]:::serving
        DockerCompose["Docker Compose Config"]:::serving
    end

    %% Prototype Layer
    subgraph "API Service (FastAPI)"
        direction TB
        FastFiltering["fast_filtering.py"]:::serving
        InferenceReq["inference_request.py"]:::serving
        LogWatcher["log_watcher.py"]:::serving
        LocalLogWatcher["local_log_watcher.py"]:::serving
    end

    subgraph "Frontend Application (Vue.js SPA)"
        direction TB
        IndexHTML["index.html"]:::ui
        MainJS["main.js"]:::ui
        AppVue["App.vue"]:::ui
        ViteConfig["vite.config.js"]:::ui
    end

    %% Visualization Tools
    subgraph "Visualization Tools"
        direction TB
        AttVis["att_visualization.py"]:::ext
        DataPlots["data_plots.py"]:::ext
        EmbeddingVis["embedding_visualization.py"]:::ext
        VisUtils["utils.py"]:::ext
    end

    %% Connections
    RawLogs -->|“Parquet Files”| Prefiltering
    Prefiltering --> LogProcessing
    LogProcessing --> MultiLang
    MultiLang --> Redundancy
    Redundancy -->|“Filtered Data”| PreprocessedData

    PreprocessedData -->|“Features”| TrainBaseline
    PreprocessedData -->|“Features”| TrainFull
    PreprocessedData -->|“Features”| TextEmbed
    PreprocessedData -->|“Features”| ModelUtils

    TrainBaseline -->|“checkpoints”| ModelRepo
    TrainFull -->|“checkpoints”| ModelRepo

    Transformers4Rec -.-> TrainBaseline
    Transformers4Rec -.-> TrainFull
    PeftLib -.-> TrainFull

    ModelRepo --> TritonServer
    ModelRepo --> LocalInfer
    ModelRepo --> EnsembleLLM

    TritonConfig --> TritonServer
    DeployTemplate --> TritonServer

    DockerCompose --> TritonServer
    DockerCompose --> FastFiltering
    DockerCompose --> Frontend

    TritonServer -->|gRPC| FastFiltering
    LocalInfer -->|“local API”| FastFiltering
    EnsembleLLM -->|“ensemble call”| FastFiltering

    FastFiltering --> InferenceReq
    InferenceReq --> LogWatcher
    LogWatcher -->|“poll logs”| RawLogs
    FastFiltering --> LocalLogWatcher

    FastFiltering <-->|“REST API”| IndexHTML
    IndexHTML --> MainJS
    MainJS --> AppVue
    AppVue --> ViteConfig

    PreprocessedData -->|“offline data”| AttVis
    PreprocessedData -->|“offline data”| DataPlots
    ModelRepo -->|“model outputs”| EmbeddingVis
    VisualizationToolsUtils -->|“helpers”| AttVis

    %% Click Events
    click Prefiltering "https://github.com/dcy0577/bim-command-recommendation/blob/main/data_processing/actual_modeling_flow_tracking_and_log_filtering/prefiltering_groupby.py"
    click LogProcessing "https://github.com/dcy0577/bim-command-recommendation/blob/main/data_processing/command_augmentation_and_workflow_generation/log_processing.ipynb"
    click MultiLang "https://github.com/dcy0577/bim-command-recommendation/blob/main/data_processing/multi_language_alignment/Preprocessing.ipynb"
    click Redundancy "https://github.com/dcy0577/bim-command-recommendation/blob/main/data_processing/redundant_command_identification_and_removal/confidence_calculation_and_filtering.ipynb"
    click PreprocessedData "https://github.com/dcy0577/bim-command-recommendation/blob/main/model/preprocess.py"
    click TrainBaseline "https://github.com/dcy0577/bim-command-recommendation/blob/main/model/train_eval_baseline_models.py"
    click TrainFull "https://github.com/dcy0577/bim-command-recommendation/blob/main/model/train_eval_full_models.py"
    click ModelUtils "https://github.com/dcy0577/bim-command-recommendation/blob/main/model/utils.py"
    click TextEmbed "https://github.com/dcy0577/bim-command-recommendation/blob/main/model/pretrained_text_embedding.py"
    click Transformers4Rec "https://github.com/dcy0577/bim-command-recommendation/blob/main/transformers4rec/torch/model/transformer.py"
    click PeftLib "https://github.com/dcy0577/bim-command-recommendation/tree/main/peft/"
    click TritonConfig "https://github.com/dcy0577/bim-command-recommendation/blob/main/deployment/deploy_template/config.pbtxt"
    click DeployTemplate "https://github.com/dcy0577/bim-command-recommendation/blob/main/deployment/deploy_template/model.py"
    click TritonServer "https://github.com/dcy0577/bim-command-recommendation/blob/main/deployment/triton_inference.py"
    click LocalInfer "https://github.com/dcy0577/bim-command-recommendation/blob/main/deployment/local_inference.py"
    click EnsembleLLM "https://github.com/dcy0577/bim-command-recommendation/blob/main/deployment/ensemble_peft_llm.py"
    click DockerCompose "https://github.com/dcy0577/bim-command-recommendation/blob/main/docker-compose.dev.deploy.yml"
    click FastFiltering "https://github.com/dcy0577/bim-command-recommendation/blob/main/prototype/web_application/fastapi/fast_filtering.py"
    click InferenceReq "https://github.com/dcy0577/bim-command-recommendation/blob/main/prototype/web_application/fastapi/inference_request.py"
    click LogWatcher "https://github.com/dcy0577/bim-command-recommendation/blob/main/prototype/web_application/fastapi/log_watcher.py"
    click LocalLogWatcher "https://github.com/dcy0577/bim-command-recommendation/blob/main/prototype/local_log_watcher.py"
    click IndexHTML "https://github.com/dcy0577/bim-command-recommendation/blob/main/prototype/web_application/frontend/index.html"
    click MainJS "https://github.com/dcy0577/bim-command-recommendation/blob/main/prototype/web_application/frontend/src/main.js"
    click AppVue "https://github.com/dcy0577/bim-command-recommendation/blob/main/prototype/web_application/frontend/src/App.vue"
    click ViteConfig "https://github.com/dcy0577/bim-command-recommendation/blob/main/prototype/web_application/frontend/vite.config.js"
    click AttVis "https://github.com/dcy0577/bim-command-recommendation/blob/main/visualization/att_visualization.py"
    click DataPlots "https://github.com/dcy0577/bim-command-recommendation/blob/main/visualization/data_plots.py"
    click EmbeddingVis "https://github.com/dcy0577/bim-command-recommendation/blob/main/visualization/embedding_visualization.py"
    click VisUtils "https://github.com/dcy0577/bim-command-recommendation/blob/main/visualization/utils.py"

    %% Styles
    classDef data fill:#cce5ff,stroke:#007bff,color:#004085
    classDef compute fill:#d4edda,stroke:#28a745,color:#155724
    classDef serving fill:#ffe5b4,stroke:#fd7e14,color:#7b2f00
    classDef ui fill:#e2d9f3,stroke:#6f42c1,color:#4e3267
    classDef ext fill:#f8f9fa,stroke:#6c757d,color:#343a40
```
