# thestrugglingblack/lumos architecture

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

- Interactive diagram: https://gitdiagram.com/thestrugglingblack/lumos
- Repository: https://github.com/thestrugglingblack/lumos

## Overview

##### Project Type and Purpose
- This is a hybrid cloud deployment project that combines AWS CDK infrastructure provisioning with a Shiny (Python) application used for interactive data analysis and visualization. The application leverages data science methodologies (inspired by the “Lumos” theme) to present insights from Harry Potter datasets.
- The README and file structure indicate a clear separation between infrastructure-as-code (in the “cdk” directory) and the Shiny application (in the “shiny” directory). Additionally, Dockerfile and task-definition.json emphasize containerization and deployment via AWS (ECS Fargate, ECR, S3, etc.).

##### Analyzing the File Structure
- Top-level directories include:
- “cdk”: Contains the AWS CDK app responsible for defining infrastructure stacks such as compute (Fargate), network (VPC, load balancer, security groups), and storage (S3, ECR).
- “shiny”: Contains the actual application code for the Shiny interactive dashboard, including analysis modules (characters, dialogue, places, spells) and static assets (www/style.css).
- Supporting files include environment templates (.env.template), Dockerfile for container builds, and GitHub workflows for CI/CD deployment.
- Inside the “cdk/lumos” subdirectories, folders are further divided into “compute”, “network”, “storage”, and “utils” – which signals the architectural segmentation of AWS resources.

##### README Insights
- The README describes the project’s purpose in “Illuminating Data” using AWS CDK to deploy a data visualization (Shiny) application.
- It clearly outlines a multi-step deployment process for various AWS resources:
- ECR (for Docker images)
- S3 (for CSV data storage)
- Network layers including Security Groups and Load Balancers
- Fargate (compute container hosting)
- The document emphasizes best practices (least privilege, separation of concerns, etc.) and outlines preliminary AWS configuration steps and Docker/virtual environment setups.

##### Elements
- How the container image moves from a local Docker build to an ECR repository.
- How network traffic is routed via the Application Load Balancer to the Fargate hosted container.
- Data flow between the Shiny app and S3.
- Annotations to note design patterns (separation of concerns, least privilege, containerization).

##### Final Advice
- Every AWS stack (ECR, S3, VPC/Network, ECS Fargate) is represented.
- Demonstrate integration points clearly, with a special note on how the Docker container (built via the Dockerfile) is deployed and connected.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client("External Clients"):::external

    %% AWS Infrastructure Provisioned via CDK
    subgraph "AWS Infrastructure (CDK Provisioned)"
        ACDK("AWS CDK Infrastructure"):::aws
        ECR("ECR Repository"):::aws
        S3("S3 Bucket"):::aws
        VPC("VPC & Network"):::aws
        ALB("Application Load Balancer"):::aws
        SG("Security Groups"):::aws
        ECS("ECS/Fargate Cluster"):::aws
    end

    %% Shiny Application Layer
    subgraph "Shiny Application Layer"
        ShinyCore("Shiny App Core (main & lumos)"):::app
        subgraph "Analysis Modules"
            Characters("Characters Analysis"):::app
            Dialogue("Dialogue Analysis"):::app
            Places("Places Analysis"):::app
            Spells("Spells Analysis"):::app
        end
        Static("Static Assets"):::app
    end

    %% Development & Deployment Tools
    subgraph "Development & Deployment"
        Docker("Docker Containerization"):::dev
        CICD("CI/CD Pipeline"):::dev
    end

    %% External traffic to AWS load balancer
    Client -->|"traffic"| ALB
    ALB -->|"routesTo"| ECS
    ECS -->|"runs"| ShinyCore

    %% Shiny internal module interactions
    ShinyCore -->|"calls"| Characters
    ShinyCore -->|"calls"| Dialogue
    ShinyCore -->|"calls"| Places
    ShinyCore -->|"calls"| Spells
    ShinyCore -->|"serves"| Static
    ShinyCore -- "accessesData" --> S3

    %% AWS Infrastructure provisioning relationships
    ACDK --> ECR
    ACDK --> S3
    ACDK --> VPC
    VPC --> ALB
    VPC --> SG
    ACDK --> ECS

    %% Containerization and CI/CD integration
    Docker -->|"buildsImage"| ECR
    CICD -->|"deploysCDK"| ACDK
    CICD -->|"triggersBuild"| Docker

    %% Click Events
    click ACDK "https://github.com/thestrugglingblack/lumos/tree/main/cdk/"
    click ECR "https://github.com/thestrugglingblack/lumos/blob/main/cdk/lumos/storage/lumos_ecr.py"
    click S3 "https://github.com/thestrugglingblack/lumos/blob/main/cdk/lumos/storage/lumos_s3.py"
    click VPC "https://github.com/thestrugglingblack/lumos/tree/main/cdk/lumos/network/"
    click ALB "https://github.com/thestrugglingblack/lumos/blob/main/cdk/lumos/network/lumos_loadbalancer.py"
    click SG "https://github.com/thestrugglingblack/lumos/blob/main/cdk/lumos/network/lumos_securtygroup.py"
    click ECS "https://github.com/thestrugglingblack/lumos/blob/main/cdk/lumos/compute/lumos_fargate.py"
    click ShinyCore "https://github.com/thestrugglingblack/lumos/blob/main/shiny/main.py"
    click Characters "https://github.com/thestrugglingblack/lumos/blob/main/shiny/analysis/characters.py"
    click Dialogue "https://github.com/thestrugglingblack/lumos/blob/main/shiny/analysis/dialogue.py"
    click Places "https://github.com/thestrugglingblack/lumos/blob/main/shiny/analysis/places.py"
    click Spells "https://github.com/thestrugglingblack/lumos/blob/main/shiny/analysis/spells.py"
    click Static "https://github.com/thestrugglingblack/lumos/blob/main/shiny/www/style.css"
    click Docker "https://github.com/thestrugglingblack/lumos/tree/main/Dockerfile"
    click CICD "https://github.com/thestrugglingblack/lumos/blob/main/.github/workflows/deployment.yml"

    %% Styles for diagram components
    classDef aws fill:#f3c623,stroke:#000,stroke-width:2px;
    classDef app fill:#7FDBFF,stroke:#000,stroke-width:2px;
    classDef dev fill:#bada55,stroke:#000,stroke-width:2px;
    classDef external fill:#ff9f1c,stroke:#000,stroke-width:2px;
```
