# abr-098/showcase architecture

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

- Interactive diagram: https://gitdiagram.com/abr-098/showcase
- Repository: https://github.com/abr-098/showcase

## Overview

##### Project type and purpose
- This is a full-stack, cloud-infrastructure management platform backed by AI.
- Purpose: accept natural-language VM requirements, use a fine-tuned OpenAI model to generate an optimal VM configuration, then provision and monitor VMs on Google Cloud via Terraform, all behind a responsive web UI.

##### Infer the file structure
- app/                ← Flask application (routes, controllers, services)
- app/ai_integration/ ← OpenAI client, prompt building, fine-tuning logic
- app/vm_manager/     ← VM lifecycle service code (create, read, update, delete)
- app/tasks/          ← Celery task definitions and workers
- config/             ← environment settings, .env loader
- infra/terraform/    ← Terraform modules, HCL scripts for GCP resources
- templates/          ← Jinja2 HTML templates
- tests/              ← unit & integration tests
- Dockerfile, docker-compose.yml
- .github/workflows/  ← CI/CD pipeline definitions
- scripts/            ← helper scripts (e.g. local setup, migrations)

##### Main components and their roles
a. User Layer
- Web browser / Mobile client → static JS/CSS → interacts with Flask API (REST/WebSocket).
b. External Services
- OpenAI API (GPT-FTM) for NLP and configuration generation
- Google Cloud APIs for provisioning (Compute Engine, Networking, IAM)
- Terraform CLI/engine invoked as a subprocess or via Terraform Cloud
c. Application Layer
- API Gateway / Flask Router – HTTP endpoints, middleware for auth & rate limiting
- Authentication subsystem – Flask-Session + Redis for session store, RBAC checks
- AI Integration service – OpenAI client wrapper & fine-tuning logic
- VM Management service – triggers Terraform jobs, tracks VM status, persists metadata
- Task Manager – Celery broker + workers for asynchronous infrastructure tasks
d. Data Layer
- PostgreSQL – persistent storage for users, VM registry, audit logs
- Redis – caching layer for sessions, Celery task results, VM status snapshots
- File storage – Terraform state files, generated config files, SSH keys
e. Infrastructure / Cloud Layer
- Terraform modules executing on GCP
- Multi-region deployment zones behind a global Load Balancer
- GCP Cloud Monitoring, structured logging, alerting

##### Relationships & Interactions
User → [Web UI static assets] → Flask API
Flask API → Authentication → Database/Redis
Flask API → AI Integration → OpenAI API → AI Integration → Flask API
Flask API → Task Manager (Celery broker) → Worker → Terraform Engine → GCP API
Terraform Engine → GCP → Compute resources; Terraform state → Storage
Worker → Database & Redis for status updates
Flask API → Database/Redis to serve real-time status to UI

##### Architectural patterns & design principles
- Layered architecture: separate presentation, business logic, data, infra
- Asynchronous processing: Celery task queue decouples long-running infra operations
- Infrastructure as Code: Terraform modules versioned alongside application code
- Micro-modular services: AI logic, VM lifecycle logic, auth logic each in its own module
- External integration façade: wrap third-party APIs behind your own service interfaces

## Diagram (Mermaid)

```mermaid
graph TB
    %% User Layer
    subgraph "User Layer"
        Browser["Web Browser\nHTML/CSS/JS"]:::frontend
        Mobile["Mobile Client\niOS/Android"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        API["Flask API Gateway\nREST/WebSocket"]:::backend
        Auth["Authentication Service\nFlask-Session, RBAC"]:::backend
        AI["AI Integration Service\nOpenAI client"]:::backend
        VM["VM Management Service\nTerraform orchestration"]:::backend
        Tasks["Task Manager\nCelery Broker & Workers"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        Postgres["PostgreSQL\nUser & VM Data"]:::data
        Redis["Redis\nSessions & Cache"]:::data
        Storage["File Storage\nTerraform state & SSH keys"]:::data
    end

    %% Cloud Infrastructure Layer
    subgraph "Cloud Infrastructure"
        LoadBalancer["Global Load Balancer"]:::cloud
        Terraform["Terraform Engine\nHCL modules"]:::cloud
        GCP["GCP Resources\nCompute, Networking"]:::cloud
        Monitoring["GCP Monitoring & Logging"]:::cloud
    end

    %% External APIs
    subgraph "External APIs"
        OpenAIAPI["OpenAI API\nGPT-FTM"]:::external
        GCPAPI["GCP API\nCompute & IAM"]:::external
    end

    %% Documentation
    subgraph "Documentation"
        Docs["README.md"]:::docs
    end

    %% Connections
    Browser -->|"HTTP/JSON"| API
    Mobile -->|"HTTP/JSON"| API

    API -->|"session auth"| Auth
    Auth -->|reads/writes| Postgres
    Auth -->|reads/writes| Redis

    API -->|"HTTP/JSON"| AI
    AI -->|"HTTPS"| OpenAIAPI
    OpenAIAPI -->|"JSON response"| AI

    API -->|"enqueue task"| Tasks
    Tasks -->|publishes| Redis
    Tasks -->|"async job"| VM

    VM -->|"executes"| Terraform
    Terraform -->|calls| GCPAPI
    Terraform -->|state stored| Storage

    VM -->|status updates| Postgres
    VM -->|cache updates| Redis
    API -->|reads real-time| Redis

    VM -->|"provisions"| GCP
    GCP -->|"resources"| GCP
    GCP -->|"metrics/logs"| Monitoring
    LoadBalancer -->|balances| GCP

    %% Click Events
    click Docs "https://github.com/abr-098/showcase/blob/main/README.md"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#DFFFE0,stroke:#28a745,color:#22863a
    classDef data fill:#FFEFD5,stroke:#d73a49,color:#d73a49
    classDef cloud fill:#F0F0F0,stroke:#6a737d,color:#586069
    classDef external fill:#EDEDED,stroke:#6a737d,color:#586069
    classDef docs fill:#FFF5B1,stroke:#DBAB09,color:#735C0F
```
