# chaharudin202-rgb/paper-bag-calculator architecture

> Architecture diagram of the GitHub repository chaharudin202-rgb/paper-bag-calculator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chaharudin202-rgb/paper-bag-calculator
- Repository: https://github.com/chaharudin202-rgb/paper-bag-calculator

## Overview

This repo is a **single-service Streamlit web application** (an MVP) that runs locally (or on a simple PaaS) and provides:
- **Cost/quotation calculation** for paper bag production
- **Plano nesting/layout optimization** (maximize pieces per sheet, include 90° rotation)
- **2D technical pattern generation** (Matplotlib)
- **3D mockup preview** (Plotly)

There’s no evidence of a separate backend, database, message bus, or multi-service topology. The “system” is essentially a **Python app process** with UI + domain logic + visualization, invoked by an end user in a browser.

##### File-tree driven architecture reading (what to extract into components)
From the tree:

- `app.py`
Likely the primary Streamlit entrypoint (UI + orchestration). This is the “web server” process for Streamlit.
- `en_app.py`
Likely an English variant of the UI (or alternate entrypoint). Treat as either:
- a second entrypoint (two deployable variants), or
- a language-specific UI module (same app, different locale).
- `requirements.txt`
Dependencies boundary: Streamlit, Matplotlib, Plotly, plus any numeric libs.
- `.devcontainer/devcontainer.json`
- `LICENSE`, `README.md`
Not runtime components.

##### Domain / Core Logic
- **Cost Calculator**
- Inputs: quantity, paper cost, print cost, finishing, etc.
- Outputs: cost breakdown + final price/quote
- **Plano Optimizer (Nesting Algorithm)**
- Inputs: plano size, bag pattern footprint, rotation allowed
- Outputs: pieces-per-sheet, layout plan, waste/efficiency metrics
- **Pattern Generator (2D)**
- Inputs: bag dimensions (L/W/H)
- Outputs: 2D technical pattern geometry (lines/polygons), ready for Matplotlib render
- **3D Model Builder**
- Inputs: bag dimensions and/or pattern
- Outputs: 3D mesh/plot primitives for Plotly

##### Visualization / Rendering
- **Matplotlib Renderer**
- Consumes 2D pattern geometry
- Produces figure displayed in Streamlit
- **Plotly Renderer**
- Consumes 3D model primitives
- Produces interactive 3D view embedded in Streamlit

##### Runtime / Hosting (minimal but include it)
- **Python Runtime / Streamlit Server Process**
- Single process handling UI + compute
- Localhost `:8501` by default
Only if the project is deployed there; README suggests local run, but the devcontainer hints container-based dev.

##### External dependencies (as “supporting systems”)
From README:
- **Streamlit**
- **Matplotlib**
- **Plotly**
(Plus any typical numeric stack inferred from requirements—only include if actually present once you open `requirements.txt`.)

##### User Browser → Streamlit UI
- “Enter dimensions, quantity, costs”
##### Streamlit UI → Domain Logic
- Calls:
- Cost Calculator
- Plano Optimizer
- Pattern Generator (2D)
- 3D Model Builder
##### Domain Logic → Visualization
- Pattern Generator → Matplotlib Renderer → Streamlit UI (figure)
- 3D Model Builder → Plotly Renderer → Streamlit UI (interactive 3D)
##### Domain Logic → Streamlit UI
- Cost breakdown results to tables/metrics
##### Streamlit UI → User Browser
- Rendered outputs

- `BagDimensions{L,W,H}`
- `PlanoSheet{width,height}`
- `CostConfig{paper,print,finishing}`
- `PatternGeometry`
- `LayoutPlan`
- `CostBreakdown`
- `PlotlyFigure` / `MatplotlibFigure`

User ↔ Streamlit App (Python) ↔ Visualization libs (supporting)
Break Streamlit App into: UI, optimizer, cost engine, 2D generator, 3D generator, renderers.

Also explicitly represent `en_app.py` as:
- either “Alternative UI entrypoint (English)” with a note “shares same logic” (if true),
- or “Separate deployment variant” (if it’s meant to be run separately).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =============== Actors / External ===============
    User["End User<br/>(Browser)"]:::actor
    StreamlitLib["Streamlit<br/>(framework)"]:::extlib
    MatplotlibLib["Matplotlib<br/>(library)"]:::extlib
    PlotlyLib["Plotly<br/>(library)"]:::extlib

    %% =============== Dev / Build-Time (Optional lane) ===============
    subgraph "Developer Environment (optional)"
        direction TB
        DevContainer["VS Code Dev Container"]:::dev
        Requirements["Python Dependencies<br/>(requirements.txt)"]:::artifact
        Readme["Project Overview / Run Instructions<br/>(README)"]:::artifact
    end

    %% =============== Runtime Boundary ===============
    subgraph "Runtime: Python + Streamlit Server Process (single service)"
        direction TB

        Server["Streamlit Server<br/>(Python process, localhost:8501)"]:::runtime

        subgraph "Presentation / UI Layer"
            direction TB
            AppUI["Streamlit UI & Orchestration<br/>(app.py)"]:::ui
            EnUI["English UI Variant / Alternate Entrypoint<br/>(en_app.py)"]:::ui
        end

        subgraph "Domain / Core Logic (logical modules)"
            direction TB
            CostCalc["Cost Calculator<br/>(breakdown + final quote)"]:::logic
            PlanoOpt["Plano Optimizer / Nesting<br/>(max pieces, 90° rotation)"]:::logic
            Pattern2D["2D Technical Pattern Generator<br/>(geometry)"]:::logic
            Model3D["3D Mockup / Model Builder<br/>(3D primitives)"]:::logic
        end

        subgraph "Visualization / Rendering"
            direction TB
            MPLRender["Matplotlib Renderer<br/>(2D figure)"]:::viz
            PlotlyRender["Plotly Renderer<br/>(interactive 3D figure)"]:::viz
        end
    end

    %% =============== Runtime Interactions ===============
    User -->|"enterInputs(L,W,H,qty,costs)"| AppUI
    User -->|"enterInputs(EN)"| EnUI

    AppUI -->|"computeCost(CostConfig,Qty)"| CostCalc
    AppUI -->|"optimizeLayout(PlanoSheet,Footprint,rotation)"| PlanoOpt
    AppUI -->|"generatePattern(BagDimensions)"| Pattern2D
    AppUI -->|"build3D(BagDimensions|Pattern)"| Model3D

    EnUI -->|"computeCost(CostConfig,Qty)"| CostCalc
    EnUI -->|"optimizeLayout(PlanoSheet,Footprint,rotation)"| PlanoOpt
    EnUI -->|"generatePattern(BagDimensions)"| Pattern2D
    EnUI -->|"build3D(BagDimensions|Pattern)"| Model3D

    Pattern2D -->|"PatternGeometry"| MPLRender
    Model3D -->|"3DPrimitives"| PlotlyRender

    MPLRender -->|"MatplotlibFigure"| AppUI
    PlotlyRender -->|"PlotlyFigure"| AppUI

    CostCalc -->|"CostBreakdown"| AppUI
    PlanoOpt -->|"LayoutPlan+Efficiency"| AppUI

    AppUI -->|"renderOutputs(tables,figures,3D)"| User
    EnUI -->|"renderOutputs(tables,figures,3D)"| User

    %% =============== Library Dependencies (conceptual) ===============
    AppUI -.->|"uses"| StreamlitLib
    EnUI -.->|"uses"| StreamlitLib
    MPLRender -.->|"uses"| MatplotlibLib
    PlotlyRender -.->|"uses"| PlotlyLib

    %% =============== Dev Flow (optional) ===============
    DevContainer -->|"installs"| Requirements
    DevContainer -->|"run(streamlit)"| Server
    Readme -.->|"guidesSetupAndRun"| DevContainer

    %% =============== Click Events (from component_mapping) ===============
    click AppUI "https://github.com/chaharudin202-rgb/paper-bag-calculator/blob/main/app.py"
    click EnUI "https://github.com/chaharudin202-rgb/paper-bag-calculator/blob/main/en_app.py"
    click CostCalc "https://github.com/chaharudin202-rgb/paper-bag-calculator/blob/main/app.py"
    click PlanoOpt "https://github.com/chaharudin202-rgb/paper-bag-calculator/blob/main/app.py"
    click Pattern2D "https://github.com/chaharudin202-rgb/paper-bag-calculator/blob/main/app.py"
    click Model3D "https://github.com/chaharudin202-rgb/paper-bag-calculator/blob/main/app.py"
    click MPLRender "https://github.com/chaharudin202-rgb/paper-bag-calculator/blob/main/app.py"
    click PlotlyRender "https://github.com/chaharudin202-rgb/paper-bag-calculator/blob/main/app.py"
    click Requirements "https://github.com/chaharudin202-rgb/paper-bag-calculator/blob/main/requirements.txt"
    click DevContainer "https://github.com/chaharudin202-rgb/paper-bag-calculator/blob/main/.devcontainer/devcontainer.json"
    click Readme "https://github.com/chaharudin202-rgb/paper-bag-calculator/blob/main/README.md"

    %% =============== Styles ===============
    classDef actor fill:#FFF2CC,stroke:#7F6000,stroke-width:1.5px,color:#111;
    classDef ui fill:#D9E1F2,stroke:#2F5597,stroke-width:1.5px,color:#111;
    classDef logic fill:#E2F0D9,stroke:#38761D,stroke-width:1.5px,color:#111;
    classDef viz fill:#FCE4D6,stroke:#C65911,stroke-width:1.5px,color:#111;
    classDef runtime fill:#E7E6E6,stroke:#595959,stroke-width:1.5px,color:#111;
    classDef extlib fill:#EFEFEF,stroke:#7A7A7A,stroke-width:1.2px,color:#111,stroke-dasharray: 4 3;
    classDef dev fill:#EAD1DC,stroke:#A64D79,stroke-width:1.5px,color:#111;
    classDef artifact fill:#F3F3F3,stroke:#666666,stroke-width:1.2px,color:#111;
```
