# devcode-it/openstamanager architecture

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

- Interactive diagram: https://gitdiagram.com/devcode-it/openstamanager
- Repository: https://github.com/devcode-it/openstamanager

## Overview

1. **Overall shape**
   - OpenSTAManager is a **single PHP modular monolith** for ERP/service management and invoicing.
   - The architecture is not a microservice split; instead, most business areas live inside the same codebase and share the same database, auth, UI shell, and task system.

2. **Request entry points**
   - HTTP traffic lands on Apache/PHP through `public/index.php`, root-level controllers like `index.php`, `view.php`, `add.php`, `edit.php`, `ajax.php`, and many module-specific scripts.
   - `.htaccess` and the `routes/` directory indicate a routed web layer, but the codebase still heavily uses **page-controller entry scripts** per feature/module.

3. **Core framework layer**
   - The `src/` tree is the shared application backbone: bootstrapping, database access, auth, API infrastructure, notifications, imports/exports, hooks, tasks, permissions, translations, uploads, and utility classes.
   - This layer provides reusable services used by all modules, so it is the main boundary between generic platform behavior and domain-specific code.

4. **Module-based domain architecture**
   - Business features are organized under `modules/`, each with its own mini-structure: `init.php`, `actions.php`, `add.php`, `edit.php`, `ajax/`, `src/`, `modals/`, `widgets/`, and sometimes `validation.php` or `variables.php`.
   - This is the primary functional boundary in the system: each module owns a domain such as clients, articles, invoices, interventions, orders, contracts, inventory, users, settings, and scheduling.

5. **Plugins as extensions**
   - `plugins/` contains optional capability packs that extend the base modules without replacing the core model.
   - Many plugins are workflow add-ons around invoicing, electronic invoicing import/export, planning, bank files, commissions, vehicle management, customer/supplier price lists, and custom business processes.
   - In architecture terms, plugins are **feature extensions** that hook into the same shared runtime, database, UI, and task infrastructure.

6. **Data model and persistence**
   - The application is backed by **MySQL/MariaDB** and uses a shared schema managed through the `update/` directory and module/plugin initialization scripts.
   - The `src/Models`, module `src/` classes, and `update/*.sql|php` files suggest a strongly database-centered architecture where domain objects map closely to tables and generated documents.
   - File storage is also part of the persistence layer via `files/`, `storage/`, and upload-related helpers.

7. **API boundary**
   - There is a distinct API surface in `src/API` plus module-local API resources under many `modules/*/src/API/v1` directories.
   - The API layer exposes domain resources such as clients, interventions, invoices, orders, payments, settings, and statuses, and is separated from the HTML UI flow by controllers, resources, DTOs, and middleware.
   - `src/Middlewares` and the `auth`/`sanctum`-style configuration indicate API authentication is treated as a separate boundary from interactive session-based access.

8. **UI composition and rendering**
   - The browser-facing UI is built from shared HTML helpers in `src/HTMLBuilder` and reusable layout fragments in `include/` and `templates/`.
   - `templates/` is especially important for architecture diagrams: it is the document/print-rendering subsystem for PDFs and reports such as invoices, DDTs, contracts, preventive quotes, accounting books, barcode labels, calendars, and dashboards.
   - This means the app has two major presentation paths: **interactive screens** and **rendered documents/reports**.

9. **Frontend asset pipeline**
   - `assets/src` contains the source JS/CSS, including shared UI behaviors, datatables, forms, navigation, widgets, and feature-specific components.
   - The repository uses **Yarn/Gulp** for asset build steps, so the frontend is a compiled asset pipeline rather than purely server-rendered PHP.
   - Some integrations are visible here too, such as CKEditor extensions, Wacom signature capture, and map-related assets.

10. **Background jobs and automation**
   - `cron.php`, `src/Tasks`, and many module/plugin task classes implement asynchronous or scheduled behaviors such as reminders, invoice/email processing, backups, updates, solleciti, and cleanup.
   - Hooks (`src/Hooks`) provide extension points for cross-module automation, letting plugins react to events like invoice creation, receipt handling, service status, or storage usage.
   - This is a separate execution path from interactive requests and should appear as a background-processing subsystem in a diagram.

11. **Integrations and external services**
   - Email is a first-class integration, with SMTP/OAuth-related modules and providers for **Google, Microsoft, and Keycloak**.
   - Electronic invoicing and receipt exchange are handled by dedicated import/export plugins and XML/XSL templates.
   - Other materially relevant integrations include signature capture, maps, FCM/token notification flows, and file transfer/storage adapters.

12. **Operational and deployment boundaries**
   - The repo includes Docker support (`docker/`) with Apache, PHP, and MySQL/MariaDB, plus update/migration assets and security tooling in GitHub Actions.
   - Runtime dependencies are PHP 8.3+ oriented, with Composer for PHP packages and Yarn for frontend builds.
   - In an architecture diagram, the deployment view should show: **web server → PHP application → MySQL/MariaDB + filesystem/storage**, plus optional external mail/API services.

13. **How the main flows connect**
   - Most user actions follow the same path: browser request → module/controller script → shared framework services → database/files/tasks → HTML/JSON response.
   - For document generation, the path is usually module data → template/rendering layer → PDF/report output.
   - For automation, the path is event or cron trigger → task/hook manager → module/plugin logic → persistence and notifications.

14. **Useful diagram takeaway**
   - The most accurate high-level diagram is a **layered modular monolith** with these boundaries: presentation, shared core framework, domain modules/plugins, persistence/storage, background tasks, and external integrations.
   - The dominant architectural feature is not a single service boundary, but the **module/plugin ecosystem** built on top of a common PHP runtime and shared data model.

Main entry points: [`modules/contratti/init.php`](https://github.com/devcode-it/openstamanager/blob/master/modules/contratti/init.php) (Modules), [`src/App.php`](https://github.com/devcode-it/openstamanager/blob/master/src/App.php) (Core services), [`bootstrap/app.php`](https://github.com/devcode-it/openstamanager/blob/master/bootstrap/app.php) (Bootstrap), [`src/HTMLBuilder/HTMLBuilder.php`](https://github.com/devcode-it/openstamanager/blob/master/src/HTMLBuilder/HTMLBuilder.php) (HTML builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & UI"]
  node_public_index["Public entry<br/>HTTP bootstrap<br/>[index.php]"]
  node_legacy_pages["Page controllers<br/>entry scripts<br/>[index.php]"]
  node_routes_web["Routes<br/>routing<br/>[web.php]"]
  node_ui_shell["UI shell<br/>presentation<br/>[top.php]"]
  node_report_templates["Templates<br/>reports<br/>[header.php]"]
  node_assets_pipeline["Assets build<br/>frontend build<br/>[custom.js]"]
end

subgraph group_core["Core Platform"]
  node_bootstrap_core["Bootstrap<br/>[app.php]"]
  node_core_services["Core services<br/>framework<br/>[App.php]"]
  node_api_framework["API framework<br/>api layer<br/>[Manager.php]"]
  node_html_builder["HTML builder<br/>ui helpers<br/>[HTMLBuilder.php]"]
  node_hook_task_system["Hooks & tasks<br/>automation<br/>[Manager.php]"]
end

subgraph group_domain["Domain Modules"]
  node_modules_bundle["Modules<br/>[init.php]"]
  node_documents_domain["Docs flow<br/>documents<br/>[init.php]"]
  node_master_data["Master data<br/>reference data<br/>[init.php]"]
  node_planning_ops["Planning ops<br/>workflow modules<br/>[init.php]"]
  node_accounting_ops["Accounting<br/>finance modules<br/>[init.php]"]
end

subgraph group_plugins["Plugins"]
  node_extensions["Plugins<br/>extensions<br/>[checks.php]"]
  node_email_integration["Email<br/>integration<br/>[init.php]"]
  node_e_invoice["E-invoicing<br/>integration<br/>[init.php]"]
end

subgraph group_ops["Operations"]
  node_persistence[("Data layer<br/>models & DB<br/>[Database.php]")]
  node_updates["Updates<br/>migrations<br/>[structure.php]"]
  node_external_services["External services<br/>integrations<br/>[services.php]"]
end

node_public_index -->|"bootstraps"| node_bootstrap_core
node_legacy_pages -->|"boots"| node_bootstrap_core
node_routes_web -->|"registers"| node_bootstrap_core
node_bootstrap_core -->|"initializes"| node_core_services
node_core_services -->|"uses"| node_persistence
node_core_services -->|"renders"| node_html_builder
node_core_services -->|"emits"| node_hook_task_system
node_core_services -->|"serves"| node_api_framework
node_html_builder -->|"composes"| node_ui_shell
node_html_builder -->|"feeds"| node_report_templates
node_assets_pipeline -->|"enhances"| node_ui_shell
node_modules_bundle -->|"depends on"| node_core_services
node_modules_bundle -->|"persists to"| node_persistence
node_modules_bundle -->|"includes"| node_documents_domain
node_modules_bundle -->|"includes"| node_master_data
node_modules_bundle -->|"includes"| node_planning_ops
node_modules_bundle -->|"includes"| node_accounting_ops
node_modules_bundle -->|"exposes"| node_api_framework
node_modules_bundle -->|"prints"| node_report_templates
node_extensions -->|"extends"| node_modules_bundle
node_extensions -->|"uses"| node_core_services
node_email_integration -->|"connects"| node_external_services
node_e_invoice -->|"connects"| node_external_services
node_hook_task_system -->|"triggers"| node_email_integration
node_hook_task_system -->|"triggers"| node_e_invoice
node_updates -->|"migrates"| node_persistence

click node_public_index "https://github.com/devcode-it/openstamanager/blob/master/public/index.php"
click node_legacy_pages "https://github.com/devcode-it/openstamanager/blob/master/index.php"
click node_routes_web "https://github.com/devcode-it/openstamanager/blob/master/routes/web.php"
click node_ui_shell "https://github.com/devcode-it/openstamanager/blob/master/include/top.php"
click node_report_templates "https://github.com/devcode-it/openstamanager/blob/master/templates/base/header.php"
click node_assets_pipeline "https://github.com/devcode-it/openstamanager/blob/master/assets/src/js/base/custom.js"
click node_bootstrap_core "https://github.com/devcode-it/openstamanager/blob/master/bootstrap/app.php"
click node_core_services "https://github.com/devcode-it/openstamanager/blob/master/src/App.php"
click node_api_framework "https://github.com/devcode-it/openstamanager/blob/master/src/API/Manager.php"
click node_html_builder "https://github.com/devcode-it/openstamanager/blob/master/src/HTMLBuilder/HTMLBuilder.php"
click node_hook_task_system "https://github.com/devcode-it/openstamanager/blob/master/src/Hooks/Manager.php"
click node_persistence "https://github.com/devcode-it/openstamanager/blob/master/src/Database.php"
click node_updates "https://github.com/devcode-it/openstamanager/blob/master/update/structure.php"
click node_modules_bundle "https://github.com/devcode-it/openstamanager/blob/master/modules/contratti/init.php"
click node_documents_domain "https://github.com/devcode-it/openstamanager/blob/master/modules/fatture/init.php"
click node_master_data "https://github.com/devcode-it/openstamanager/blob/master/modules/anagrafiche/init.php"
click node_planning_ops "https://github.com/devcode-it/openstamanager/blob/master/modules/interventi/init.php"
click node_accounting_ops "https://github.com/devcode-it/openstamanager/blob/master/modules/primanota/init.php"
click node_extensions "https://github.com/devcode-it/openstamanager/blob/master/plugins/checks.php"
click node_email_integration "https://github.com/devcode-it/openstamanager/blob/master/modules/emails/init.php"
click node_e_invoice "https://github.com/devcode-it/openstamanager/blob/master/plugins/exportFE/init.php"
click node_external_services "https://github.com/devcode-it/openstamanager/blob/master/config/services.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_index,node_legacy_pages,node_routes_web,node_ui_shell,node_report_templates,node_assets_pipeline toneBlue
class node_bootstrap_core,node_core_services,node_api_framework,node_html_builder,node_hook_task_system toneAmber
class node_modules_bundle,node_documents_domain,node_master_data,node_planning_ops,node_accounting_ops toneMint
class node_extensions,node_email_integration,node_e_invoice toneRose
class node_persistence,node_updates,node_external_services toneIndigo
```

## Components

### Entry & UI

HTTP entry points, shared presentation, and document rendering.

- [Public entry](https://github.com/devcode-it/openstamanager/blob/master/public/index.php): HTTP bootstrap · Main web entry point for browser requests. · `public/index.php`
- [Page controllers](https://github.com/devcode-it/openstamanager/blob/master/index.php): entry scripts · Root-level controller scripts such as index, view, add, edit, and ajax handlers. · `index.php`
- [Routes](https://github.com/devcode-it/openstamanager/blob/master/routes/web.php): routing · Web and API route definitions. · `routes/web.php`
- [UI shell](https://github.com/devcode-it/openstamanager/blob/master/include/top.php): presentation · Shared HTML/layout helpers and reusable page fragments. · `include/top.php`
- [Templates](https://github.com/devcode-it/openstamanager/blob/master/templates/base/header.php): reports · Print and PDF document rendering subsystem. · `templates/base/header.php`
- [Assets build](https://github.com/devcode-it/openstamanager/blob/master/assets/src/js/base/custom.js): frontend build · Compiled JS/CSS source and build pipeline for interactive UI. · `assets/src/js/base/custom.js`

### Core Platform

Shared framework services used across the monolith.

- [Bootstrap](https://github.com/devcode-it/openstamanager/blob/master/bootstrap/app.php): runtime bootstrap · Application bootstrapping and service provider wiring. · `bootstrap/app.php`
- [Core services](https://github.com/devcode-it/openstamanager/blob/master/src/App.php): framework · Database, auth, permissions, translations, uploads, settings, notifications, and tasks. · `src/App.php`
- [API framework](https://github.com/devcode-it/openstamanager/blob/master/src/API/Manager.php): api layer · Shared API resources, controllers, middleware, DTOs, and responses. · `src/API/Manager.php`
- [HTML builder](https://github.com/devcode-it/openstamanager/blob/master/src/HTMLBuilder/HTMLBuilder.php): ui helpers · Shared form, field, button, widget, and integration renderers. · `src/HTMLBuilder/HTMLBuilder.php`
- [Hooks & tasks](https://github.com/devcode-it/openstamanager/blob/master/src/Hooks/Manager.php): automation · Cross-module event hooks and background task execution. · `src/Hooks/Manager.php`

### Domain Modules

Primary business subsystems implemented inside the monolith.

- [Modules](https://github.com/devcode-it/openstamanager/blob/master/modules/contratti/init.php): business modules · Primary domain subsystems for ERP and service workflows. · `modules/contratti/init.php`
- [Docs flow](https://github.com/devcode-it/openstamanager/blob/master/modules/fatture/init.php): documents · Preventivi, ordini, DDT, fatture, contracts, interventions, and related line-item flows. · `modules/fatture/init.php`
- [Master data](https://github.com/devcode-it/openstamanager/blob/master/modules/anagrafiche/init.php): reference data · Clients, articles, technicians, settings, VAT, banks, categories, and lookup tables. · `modules/anagrafiche/init.php`
- [Planning ops](https://github.com/devcode-it/openstamanager/blob/master/modules/interventi/init.php): workflow modules · Scheduling, tasks, calendars, checklists, events, and service execution. · `modules/interventi/init.php`
- [Accounting](https://github.com/devcode-it/openstamanager/blob/master/modules/primanota/init.php): finance modules · Prima nota, due dates, payments, bank handling, statements, and reporting. · `modules/primanota/init.php`

### Plugins

Optional feature extensions built on the same runtime.

- [Plugins](https://github.com/devcode-it/openstamanager/blob/master/plugins/checks.php): extensions · Optional add-ons that extend core workflows without replacing the monolith. · `plugins/checks.php`
- [Email](https://github.com/devcode-it/openstamanager/blob/master/modules/emails/init.php): integration · SMTP/OAuth mail accounts, templates, sending, receipts, and notifications. · `modules/emails/init.php`
- [E-invoicing](https://github.com/devcode-it/openstamanager/blob/master/plugins/exportFE/init.php): integration · Import/export and XML/XSL processing for electronic invoicing and receipts. · `plugins/exportFE/init.php`

### Operations

Database updates, scheduled jobs, and infrastructure concerns.

- [Data layer](https://github.com/devcode-it/openstamanager/blob/master/src/Database.php): models & DB · Shared models, database access, files, storage, and schema evolution. · `src/Database.php`
- [Updates](https://github.com/devcode-it/openstamanager/blob/master/update/structure.php): migrations · Versioned SQL/PHP update scripts and schema maintenance. · `update/structure.php`
- [External services](https://github.com/devcode-it/openstamanager/blob/master/config/services.php): integrations · Mail providers, maps, FCM/tokens, OAuth providers, signature devices, and FTP/local storage. · `config/services.php`

## Connections

- Public entry → Bootstrap: bootstraps · Web requests enter the PHP application through the public front controller.
- Page controllers → Bootstrap: boots · Legacy page-controller scripts rely on the same application bootstrap.
- Routes → Bootstrap: registers · Route definitions are loaded into the shared runtime.
- Bootstrap → Core services: initializes · Bootstrapping wires shared services and configuration.
- Core services → Data layer: uses · Core services read and write the shared database and storage.
- Core services → HTML builder: renders · Shared services feed the HTML/component rendering layer.
- Core services → Hooks & tasks: emits · Business events and scheduled work are coordinated through hooks and tasks.
- Core services → API framework: serves · The application exposes a dedicated JSON/API surface.
- HTML builder → UI shell: composes · Shared helpers assemble the interactive UI shell.
- HTML builder → Templates: feeds · The same data and helpers support print/document rendering.
- Assets build → UI shell: enhances · Compiled assets provide client-side behavior for the UI shell.
- Modules → Core services: depends on · Modules use the shared framework for auth, DB, uploads, and notifications.
- Modules → Data layer: persists to · Business modules map closely to shared tables and files.
- Modules → Docs flow: includes · A large portion of the module set handles document-centric workflows.
- Modules → Master data: includes · Reference and master-data modules underpin the rest of the ERP.
- Modules → Planning ops: includes · Scheduling and service-execution modules form another major cluster.
- Modules → Accounting: includes · Accounting and payment modules operate on the same domain model.
- Modules → API framework: exposes · Many modules publish domain resources through the API layer.
- Modules → Templates: prints · Modules feed document and report templates.
- Plugins → Modules: extends · Plugins hook into existing modules and workflows.
- Plugins → Core services: uses · Plugins share the same runtime, auth, tasks, and data layer.
- Email → External services: connects · Mail flow integrates with SMTP and OAuth providers.
- E-invoicing → External services: connects · E-invoicing exchange interacts with external authorities and file-based exchanges.
- Hooks & tasks → Email: triggers · Tasks and hooks drive automated mail and notification flows.
- Hooks & tasks → E-invoicing: triggers · Background automation handles invoice import/export and receipt flows.
- Updates → Data layer: migrates · Update scripts evolve the shared schema and stored data.