# aliozertekin/flask_inventory_system architecture

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

- Interactive diagram: https://gitdiagram.com/aliozertekin/flask_inventory_system
- Repository: https://github.com/aliozertekin/flask_inventory_system

## Overview

##### Project type and purpose
- This is a full-stack web application for Inventory, Order & Shipment Management.
- Backend: Flask (Python 3.13+), connects to Oracle Database (21c+) via cx_Oracle.
- Frontend: HTML/CSS/JavaScript templates served by Flask.
- Additional component: Serial-port integration for real-time inventory updates (PySerial).

##### File structure
- app.py: Flask app entry point, initializes routes and database connection.
- db/connection.py: Oracle connection setup.
- db/sql/: PL/SQL scripts for schema creation, installation, population, methods, triggers, views, packages.
- routes/: Flask view-functions grouped by feature (auth, customers, inventory, orders, shipments, etc.).
- modules/utilities.py: Shared helper functions.
- serial/: Scripts for machine simulation (simulate_machine.py) and serial receiver (receiver.py).
- static/: CSS (style.css), JavaScript (search.js), fonts.
- templates/: Jinja2 HTML pages for each view.
- images/: Screenshots for README.

##### Key architectural insights from README
- MVC pattern:
- Models & procedures in Oracle (tables, views, stored procedures, triggers).
- Controllers in Flask routes/.
- Views in templates/ + static assets.
- Real-time inventory updates via a long-running serial port listener that calls a PL/SQL procedure.
- Audit logging via database triggers.
- Client (browser) ↔ Flask ↔ Oracle interactions.
- Optional component: machine simulator to test serial feed.

##### Main components
a. Client web browser (UI layer)
- Requests HTML/JSON pages via HTTP(S).
b. Flask Application Server
- app.py and routes/*.
- Business logic, session/auth handling, input validation.
- Utilities module for shared code.
c. Oracle Database
- Core tables: PRODUCTS, STORES, CUSTOMERS, ORDERS, ORDER_ITEMS, SHIPMENTS, INVENTORY.
- Logging tables (e.g., ORDER_LOG, INVENTORY_LOG, AUDIT_LOG).
- Views (e.g., INVENTORY_VIEW, ORDERS_VIEW).
- Stored procedures & packages (ADD_INVENTORY, ADD_ORDER, etc.).
- Triggers for auditing and restock logic.
d. Serial Integration Service
- receiver.py: Listens on serial port, processes incoming data, calls ADD_INVENTORY.
- simulate_machine.py: Generates fake serial messages for testing.
e. External Clients / Services (optional)
- Barcode scanners or sensors sending data via serial port.
f. Static Assets CDN (or local folder)
- style.css, search.js, fonts.

##### Interactions and data flows
- Web flow: Browser → (HTTP) → Flask Routes → (cx_Oracle) → PL/SQL procedures / queries → Oracle DB → back to Flask → Browser.
- Real-time flow: Hardware device → Serial Port → receiver.py → cx_Oracle callproc(ADD_INVENTORY) → Oracle DB → Inventory updated → receiver logs/console.
- Simulator flow: simulate_machine.py → Local serial port emulator → receiver.py → same as real-time flow.
- Audit/logging: DB triggers fire on data changes to write to log tables.

##### Architectural patterns & design principles
- MVC separation of concerns (Templates, Routes/Controllers, DB Layer).
- Modularization: routes/ for endpoints, modules/ for helpers, db/sql/ for schema & logic.
- Event-driven processing for serial data.
- Use of stored procedures/packages to encapsulate business logic in DB.
- Triggers for cross-cutting concerns (audit, restock).

## Diagram (Mermaid)

```mermaid
graph TB
  %% Presentation Layer
  subgraph "Presentation Layer"
    Browser["Browser UI"]:::frontend
    subgraph "Static Assets"
      CSS["style.css"]:::static
      JS["search.js"]:::static
      Fonts["fonts/"]:::static
    end
    subgraph "Templates (Views)"
      Templates["Jinja2 HTML Templates"]:::template
    end
  end

  %% Application Layer
  subgraph "Application Layer"
    FlaskApp["Flask App"]:::flask
    subgraph "Controllers (routes)"
      Auth["auth.py"]:::controller
      Customers["customers.py"]:::controller
      InventoryRoute["inventory.py"]:::controller
      Orders["orders.py"]:::controller
      OrderItems["order_items.py"]:::controller
      Shipments["shipments.py"]:::controller
      ProductRoute["product.py"]:::controller
      StoreRoute["store.py"]:::controller
      LogRoute["log.py"]:::controller
      MiscRoutes["index.py\nprivacy.py\nterms.py\nlots.py"]:::controller
    end
    Utilities["utilities.py"]:::utility
    Connection["connection.py"]:::dbconn
  end

  %% Data Layer
  subgraph "Data Layer"
    OracleDB["Oracle Database"]:::database
    DBDetails(("Tables, Views, Stored Procedures,\nTriggers, Logging Tables")):::database
    OracleDB --> DBDetails
  end

  %% Integration Layer
  subgraph "Integration Layer"
    SerialReceiver["receiver.py"]:::serial
    Simulator["simulate_machine.py"]:::serial
  end

  %% Data Flows
  Browser -->|"HTTP(S)"| FlaskApp
  FlaskApp -->|"Serves Templates"| Templates
  FlaskApp -->|"Serves Static Assets"| CSS
  FlaskApp -->|"Serves Static Assets"| JS
  FlaskApp -->|"Serves Static Assets"| Fonts
  FlaskApp -->|"cx_Oracle"| OracleDB
  SerialReceiver -->|"cx_Oracle callproc"| OracleDB
  Simulator -->|"pySerial"| SerialReceiver

  %% Click Events
  click FlaskApp "https://github.com/aliozertekin/flask_inventory_system/blob/main/app.py"
  click Connection "https://github.com/aliozertekin/flask_inventory_system/blob/main/db/connection.py"
  click DBDetails "https://github.com/aliozertekin/flask_inventory_system/tree/main/db/sql/"
  click Auth "https://github.com/aliozertekin/flask_inventory_system/blob/main/routes/auth.py"
  click Customers "https://github.com/aliozertekin/flask_inventory_system/blob/main/routes/customers.py"
  click InventoryRoute "https://github.com/aliozertekin/flask_inventory_system/blob/main/routes/inventory.py"
  click Orders "https://github.com/aliozertekin/flask_inventory_system/blob/main/routes/orders.py"
  click OrderItems "https://github.com/aliozertekin/flask_inventory_system/blob/main/routes/order_items.py"
  click Shipments "https://github.com/aliozertekin/flask_inventory_system/blob/main/routes/shipments.py"
  click ProductRoute "https://github.com/aliozertekin/flask_inventory_system/blob/main/routes/product.py"
  click StoreRoute "https://github.com/aliozertekin/flask_inventory_system/blob/main/routes/store.py"
  click LogRoute "https://github.com/aliozertekin/flask_inventory_system/blob/main/routes/log.py"
  click MiscRoutes "https://github.com/aliozertekin/flask_inventory_system/blob/main/routes/index.py"
  click Utilities "https://github.com/aliozertekin/flask_inventory_system/blob/main/modules/utilities.py"
  click SerialReceiver "https://github.com/aliozertekin/flask_inventory_system/blob/main/serial/receiver.py"
  click Simulator "https://github.com/aliozertekin/flask_inventory_system/blob/main/serial/simulate_machine.py"
  click CSS "https://github.com/aliozertekin/flask_inventory_system/blob/main/static/style.css"
  click JS "https://github.com/aliozertekin/flask_inventory_system/blob/main/static/scripts/search.js"
  click Fonts "https://github.com/aliozertekin/flask_inventory_system/tree/main/static/fonts/"

  %% Styles
  classDef frontend fill:#D6E9FE,stroke:#2B65EC,color:#2B65EC;
  classDef static fill:#E8F5E9,stroke:#1E8E3E,color:#1E8E3E;
  classDef template fill:#FFF3E0,stroke:#FB8C00,color:#FB8C00;
  classDef flask fill:#FFE5EC,stroke:#E91E63,color:#E91E63;
  classDef controller fill:#E3F2FD,stroke:#2196F3,color:#1976D2;
  classDef utility fill:#F3E5F5,stroke:#9C27B0,color:#7B1FA2;
  classDef dbconn fill:#E0F7FA,stroke:#00ACC1,color:#00838F;
  classDef database fill:#FFFDE7,stroke:#FBC02D,color:#F57F17;
  classDef serial fill:#EDE7F6,stroke:#5E35B1,color:#4527A0;
```
