devcode-it/openstamanager

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.