# riddleroseheart/polyprint3d architecture

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

- Interactive diagram: https://gitdiagram.com/riddleroseheart/polyprint3d
- Repository: https://github.com/riddleroseheart/polyprint3d

## Overview

##### Project Type & Purpose
- PolyPrint 3D is a full-stack application with two clear halves:
- A Python/Flask-based backend that handles API endpoints, slicing logic, printer control (integrated with OctoPrint), authentication, file management, and database operations.
- A JavaScript-based frontend built with Three.js providing the web UI.
- Key functionality revolves around automatically slicing 3D models into smaller parts and distributing print jobs to multiple 3D printers.

##### Analyzing the File Structure
- Backend:
- Contains the core Flask application (backend/main.py) that initializes the server.
- The “routes” directory defines various API endpoints (e.g., alert_routes, auth_routes, file_routes, printer_routes, slicer_routes, etc.).
- The “services” directory encapsulates business logic – with specialized services for alerts, authentication, notifications, file handling, and printing (including a deeper printer service hierarchy).
- The “database” subdirectory manages database configuration, models and includes the local database file (polyprint.db) as well as config settings.
- The “slicer” folder houses the slicing logic, including configuration files (in backend/slicer/config) and scripts (in backend/slicer/scripts) to manage slicing operations.
- Additional utility functions and email templates for notifications are present in backend/utils and backend/templates respectively.
- Frontend:
- Built in JavaScript (React structure indicated by components, src, public folders) and employs Three.js.
- API configuration and endpoints references (in frontend/src/api) show clear integration with backend services.
- Support files:
- Setup scripts (setup.sh/setup.bat) and run scripts (run.sh/run.bat) provide instructions for environment configuration and deployment.
- Environment variable template (.env.template) is essential for configuration (e.g., FLASK_APP, DATABASE_URL).

##### Architectural Overview
a. Main Components:
- Frontend:
- Web UI (React components, Three.js visualization)
- API Communication layer (axiosConfig with endpoints for auth, alert, printer, file, slicer, etc.)
- Backend:
- API Server (Flask) that handles incoming HTTP requests.
- Routing Layer (under backend/routes) maps endpoints to business logic.
- Service Layer:
▪ Core business logic including Alert, Auth, File, Notification, Printer control (with further subdivisions: connection, job, management, etc.), Slicer, and Octoprint integration.
- Database:
▪ Database configuration and models housed in backend/database.
- Slicer Engine:
▪ Slicing operations via dedicated scripts and configuration files.
- External Services:
- OctoPrint for printer control/integration.
- Email notification system (using templates in backend/templates/emails).

b. Relationships and Interactions:
- The Frontend communicates with the Backend via HTTP requests to the defined API endpoints.
- The API server routes requests to the appropriate service layer components.
- Services interact with the database for data persistence (configuration, job statuses, user data, etc.).
- Printer services interact with external services such as OctoPrint to manage print jobs.
- The Slicer component processes 3D models, communicating with both the database (for configuration and status tracking) and printer services (for job distribution).

c. Architectural Patterns & Design Principles:
- Layered Architecture: Clear separation between presentation (Frontend), API (Routes), business logic (Services), and data (Database).
- Modular Design: Separate directories for routes, services, and database operations to promote maintainability.
- Integration & Extensibility: Integration with external printer control via OctoPrint, and use of configuration files/scripts for the slicer.
- Micro-modularity even within services – particularly for the printer where there are multiple subservices handling different aspects (connection, file handling, job management).

d. Key Technologies & Frameworks:
- Backend: Python, Flask, and possibly SQLAlchemy (for database models) along with custom code for slicing.
- Frontend: JavaScript, React (implied by file structure), and Three.js for 3D visualization.
- External: OctoPrint for interfacing with printers.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend"
        FE1["Web UI (React/Three.js Client)"]:::frontend
        FE4["JS Entry Point"]:::frontend
        FE3["React Components"]:::frontend
        FE2["API Communication Layer"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        B1["API Server (Flask)"]:::backend

        %% Routing Layer
        subgraph "Routing Layer"
            R1["Alert Routes"]:::routes
            R2["Auth Routes"]:::routes
            R3["File Routes"]:::routes
            R4["Printer Routes"]:::routes
            R5["Slicer Routes"]:::routes
            R6["Config Routes"]:::routes
        end

        %% Service Layer
        subgraph "Service Layer"
            S1["Alert Service"]:::services
            S2["Auth Service"]:::services
            S3["File Service"]:::services
            S4["Notification Service"]:::services
            S5["OctoPrint Integration"]:::services
            subgraph "Printer Control Services"
                P1["Base Printer"]:::services
                P2["Connection Service"]:::services
                P3["Printer File Service"]:::services
                P4["Job Service"]:::services
                P5["Management Service"]:::services
                P6["Printer Queue Service"]:::services
            end
            S7["Slicer Service"]:::services
        end

        %% Database
        subgraph "Database"
            D1["DB Config & Models"]:::database
            D2["Local DB"]:::database
        end

        %% Slicer Engine
        subgraph "Slicer Engine"
            SL1["Slicer Config Files"]:::slicer
            SL2["Slicer Scripts"]:::slicer
            SL3["3D Model Input"]:::slicer
        end

        %% Utilities
        subgraph "Utilities"
            E1["Email Notification Templates"]:::utils
            subgraph "Environment & Setup"
                ES1["Env Template"]:::utils
                ES2["Setup/Run Scripts"]:::utils
            end
        end
    end

    %% External Services
    EX1["OctoPrint"]:::external

    %% Connections - Frontend to Backend
    FE1 --> FE2
    FE3 --> FE2
    FE4 --> FE2
    FE2 -->|"HTTP_Request"| B1

    %% API Server routes to Routing Layer
    B1 --> R1
    B1 --> R2
    B1 --> R3
    B1 --> R4
    B1 --> R5
    B1 --> R6

    %% Routing Layer to Service Layer
    R1 -->|"calls"| S1
    R2 -->|"calls"| S2
    R3 -->|"calls"| S3
    R4 -->|"calls"| P1
    R4 -->|"calls"| S5
    R5 -->|"calls"| S7
    R6 -->|"calls"| S4

    %% Service Layer interactions with Database
    S1 -->|"persist"| D1
    S2 -->|"persist"| D1
    S3 -->|"persist"| D1
    S4 -->|"persist"| D1
    S5 -->|"interface"| EX1
    P1 -->|"data"| D1
    P2 -->|"data"| D1
    P3 -->|"data"| D1
    P4 -->|"data"| D1
    P5 -->|"data"| D1
    P6 -->|"data"| D1
    S7 -->|"persist"| D1

    D1 -->|"stored_in"| D2

    %% Slicer Service to Slicer Engine
    S7 -->|"process"| SL1
    S7 -->|"process"| SL2
    S7 -->|"process"| SL3

    %% Notification Service to Email Templates
    S4 -->|"notify"| E1

    %% Printer Integration with External Service
    S5 -->|"control"| EX1
    P1 -->|"control"| EX1

    %% Environment & Setup initialization
    ES1 -->|"init"| B1
    ES2 -->|"init"| B1

    %% Class Definitions for Colors
    classDef frontend fill:#FCE4EC,stroke:#880E4F,stroke-width:2px;
    classDef backend fill:#E3F2FD,stroke:#0D47A1,stroke-width:2px;
    classDef routes fill:#E8F5E9,stroke:#1B5E20,stroke-width:2px;
    classDef services fill:#FFF3E0,stroke:#E65100,stroke-width:2px;
    classDef database fill:#E0F7FA,stroke:#006064,stroke-width:2px;
    classDef slicer fill:#FFFDE7,stroke:#F57F17,stroke-width:2px;
    classDef utils fill:#F3E5F5,stroke:#4A148C,stroke-width:2px;
    classDef external fill:#FFEBEE,stroke:#B71C1C,stroke-width:2px;

    %% Click Events - Frontend
    click FE1 "https://github.com/riddleroseheart/polyprint3d/blob/main/frontend/index.html"
    click FE2 "https://github.com/riddleroseheart/polyprint3d/tree/main/frontend/src/api/"
    click FE3 "https://github.com/riddleroseheart/polyprint3d/tree/main/frontend/src/components"
    click FE4 "https://github.com/riddleroseheart/polyprint3d/blob/main/frontend/src/index.js"

    %% Click Events - API Server
    click B1 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/main.py"

    %% Click Events - Routing Layer
    click R1 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/routes/alert_routes.py"
    click R2 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/routes/auth_routes.py"
    click R3 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/routes/file_routes.py"
    click R4 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/routes/printer_routes.py"
    click R5 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/routes/slicer_routes.py"
    click R6 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/routes/config_routes.py"

    %% Click Events - Service Layer
    click S1 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/services/alert_service.py"
    click S2 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/services/auth_service.py"
    click S3 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/services/file_service.py"
    click S4 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/services/notification_service.py"
    click S5 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/services/octoprint_service.py"
    click P1 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/services/printer/base_service.py"
    click P2 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/services/printer/connection_service.py"
    click P3 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/services/printer/file_service.py"
    click P4 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/services/printer/job_service.py"
    click P5 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/services/printer/management_service.py"
    click P6 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/services/printer_queue_service.py"
    click S7 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/services/slicer_service.py"

    %% Click Events - Database
    click D1 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/database/config.py"
    click D2 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/database/polyprint.db"

    %% Click Events - Slicer Engine
    click SL1 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/slicer/config/config.ini"
    click SL2 "https://github.com/riddleroseheart/polyprint3d/blob/main/backend/slicer/scripts/slicer.py"
    click SL3 "https://github.com/riddleroseheart/polyprint3d/tree/main/backend/slicer/input"

    %% Click Events - Utilities and Environment
    click E1 "https://github.com/riddleroseheart/polyprint3d/tree/main/backend/templates/emails"
    click ES1 "https://github.com/riddleroseheart/polyprint3d/blob/main/.env.template"
    click ES2 "https://github.com/riddleroseheart/polyprint3d/blob/main/setup.sh"
```
