# iamrbtm/dfp_os architecture

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

- Interactive diagram: https://gitdiagram.com/iamrbtm/dfp_os
- Repository: https://github.com/iamrbtm/dfp_os

## Overview

1. **Top-level shape**
   - The repo is a **modular Flask monolith** for the main Dude Fish OS application, plus two separate deployable services under `services/`:
     - `services/audit-log`: dedicated audit event service
     - `services/dfpos-api-docs`: standalone API docs renderer
   - The main app is the user-facing system; the services are isolation boundaries for compliance/docs concerns.

2. **Main application stack**
   - `app:create_app` is the application factory.
   - The app uses **SQLAlchemy + Flask-Migrate** for persistence, **Flask-Login** for session auth, **Flask-WTF** for forms, and **Flask-Smorest** for the JSON API/OpenAPI layer.
   - Templates and static assets indicate a server-rendered UI with a Tailwind-built frontend, not a SPA.

3. **Request flow in the main app**
   - Browser requests enter Flask blueprints in `app/blueprints/*`.
   - Blueprints call into `app/services/*` for business rules and mutations.
   - Services read/write `app/models/*`, validate/shape data via `app/forms/*` and `app/schemas/*`, then persist to MariaDB.
   - This is the primary boundary: **routes handle HTTP, services handle domain logic, models hold data**.

4. **Domain modules / business capabilities**
   - The main system is split into functional modules: **customers, products/catalog, orders, POS, receipts, inventory, expenses, markets, print jobs, printers, prep tasks, notifications, analytics, custom orders, settings, auth, API tokens**.
   - `app/module_registry.py` is important: it centralizes module metadata, dependencies, permissions, nav/API exposure, and feature flags. This is the repo’s internal module governance layer.

5. **Feature flags and operational control**
   - Feature flags can come from persisted `FeatureFlag`/`Setting` records.
   - Disabled modules are blocked server-side for both UI routes and `/api/v1` resources.
   - `Business` is the current single-tenant anchor, with nullable `business_id` fields added across major records to support later SaaS-style separation.

6. **Core transactional data flows**
   - **POS / orders / inventory** are tightly coupled: sales create order/POS records and deduct inventory, recording `InventoryMovement` rows.
   - **Receipts** form a separate operational pipeline: uploaded receipts are reviewed/approved before expense ledger entries are created.
   - **Print jobs / printers / prep tasks** represent production workflow objects, feeding the manufacturing side of the business.
   - **Customers, custom orders, markets, and expenses** extend the same transactional store rather than living in separate databases.

7. **API surface**
   - The app exposes a code-first JSON API under `app/blueprints/api/*`.
   - Schemas live in `app/schemas/*`; API documentation is generated automatically from Flask-Smorest decorators.
   - `app/blueprints/api_tokens` and `app/models/api_token.py` indicate token-authenticated API access for non-browser clients and internal integrations.

8. **Authentication and admin shell**
   - Human users authenticate through the Flask session/login flow with hashed passwords in `User`.
   - `app/blueprints/dashboard` provides the protected internal shell.
   - `app/services/admin_mutations.py`, `app/cli.py`, and seed flows support initial/admin setup and operational management.

9. **Background and scheduled processing**
   - `app/celery_app.py` and `app/tasks/*` show an async worker lane for heavier jobs like cost calculation, model analysis, trend calibration, and trend scout execution.
   - This is the main off-request processing boundary: web requests enqueue work, workers perform longer-running calculations and updates.

10. **Trend Scout AI subsystem**
   - `app/services/ai/trend_scout/*` is a distinct subdomain with its own analyzers, source adapters, and models.
   - It aggregates signals from external/public sources such as Etsy, Pinterest, Reddit, TikTok, Google Trends, BGG, Printables, Makerworld, MyMiniFactory, and internal demand.
   - Supporting services for backtesting, calibration, pruning, history, monitoring, and weights suggest a full pipeline:
     **ingest signals -> score opportunities -> calibrate/backtest -> monitor task health -> persist trend models/results**.

11. **Receipts and expense automation**
   - Receipt handling is split into several services: OCR/AI providers, image preprocessing, duplicate detection, audit logging, allocation, and approval workflows.
   - The architecture intentionally keeps automated parsing separate from final accounting entry creation, which reduces bad expense writes and allows manual review gates.

12. **Audit logging as a separate service**
   - `services/audit-log` is a standalone service with its own API, database layer, hashing, search, Redis stream ingestion, and worker.
   - Its structure implies an append-only, tamper-evident audit trail with idempotency and asynchronous ingestion from the main app or other clients.
   - This is a clear compliance boundary: operational app data stays in the main monolith, immutable audit history lives elsewhere.

13. **Docs microservice**
   - `services/dfpos-api-docs` fetches `/api/openapi.json` from the main app and renders Redoc.
   - It has no database dependency and exists to isolate API documentation delivery from the core app runtime.

14. **Infrastructure and persistence**
   - The main persistence layer is **MariaDB**, with Alembic migrations in `migrations/`.
   - Docker Compose provides the main app, database, and optional local-dev/prod-adjacent services.
   - Tailwind CSS is built separately into `app/static/dist/app.css`, so the UI depends on a frontend build step but not a JS application runtime.

Main entry points: [`app/blueprints`](https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints) (Blueprints), [`app/__init__.py`](https://github.com/iamrbtm/dfp_os/blob/main/app/__init__.py) (App Factory), [`app/services`](https://github.com/iamrbtm/dfp_os/tree/main/app/services) (Services), [`app/models`](https://github.com/iamrbtm/dfp_os/tree/main/app/models) (Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_main_app["Main App"]
  node_app_factory["App Factory<br/>Flask factory<br/>[__init__.py]"]
  node_module_registry["Module Registry<br/>governance<br/>[module_registry.py]"]
  node_blueprints_shell["Blueprints<br/>HTTP routes"]
  node_services_layer["Services<br/>domain logic"]
  node_forms_schemas["Forms & Schemas<br/>validation layer"]
  node_models_layer[("Models<br/>ORM entities")]
  node_auth_shell["Auth Shell<br/>login/session"]
  node_catalog_ops["Catalog Ops<br/>merchandise"]
  node_finance_ops["Finance Ops<br/>receipts/expenses"]
  node_production_ops["Production Ops<br/>workflow"]
  node_market_ops["Market Ops<br/>field ops"]
  node_analytics_api["API Layer<br/>JSON API"]
  node_trend_scout["Trend Scout<br/>AI pipeline"]
end

subgraph group_async["Async Work"]
  node_celery_lane["Worker Lane<br/>async jobs<br/>[celery_app.py]"]
end

subgraph group_services["Deployable Services"]
  node_audit_service["Audit Log Service<br/>FastAPI service"]
  node_docs_service["API Docs Service<br/>docs renderer"]
end

subgraph group_infra["Infrastructure"]
  node_persistence[("MariaDB<br/>primary datastore")]
  node_migrations["Migrations<br/>schema evolution"]
  node_redis_bus["Redis Streams<br/>event bus"]
end

node_app_factory -->|"loads modules"| node_module_registry
node_app_factory -->|"registers"| node_blueprints_shell
node_app_factory -->|"wires"| node_services_layer
node_app_factory -->|"binds ORM"| node_models_layer
node_app_factory -->|"exposes"| node_analytics_api
node_blueprints_shell -->|"includes"| node_auth_shell
node_blueprints_shell -->|"includes"| node_catalog_ops
node_blueprints_shell -->|"includes"| node_finance_ops
node_blueprints_shell -->|"includes"| node_production_ops
node_blueprints_shell -->|"includes"| node_market_ops
node_blueprints_shell -->|"mounts"| node_analytics_api
node_blueprints_shell -->|"calls"| node_services_layer
node_services_layer -->|"validates"| node_forms_schemas
node_services_layer -->|"reads/writes"| node_models_layer
node_services_layer -->|"stores"| node_persistence
node_models_layer -->|"maps to"| node_persistence
node_migrations -->|"evolves"| node_persistence
node_trend_scout -->|"offloads"| node_celery_lane
node_trend_scout -->|"persists"| node_persistence
node_celery_lane -->|"updates"| node_persistence
node_audit_service -->|"ingests"| node_redis_bus
node_audit_service -->|"stores"| node_persistence
node_docs_service -->|"fetches spec"| node_analytics_api

click node_app_factory "https://github.com/iamrbtm/dfp_os/blob/main/app/__init__.py"
click node_module_registry "https://github.com/iamrbtm/dfp_os/blob/main/app/module_registry.py"
click node_blueprints_shell "https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints"
click node_services_layer "https://github.com/iamrbtm/dfp_os/tree/main/app/services"
click node_forms_schemas "https://github.com/iamrbtm/dfp_os/tree/main/app/forms"
click node_models_layer "https://github.com/iamrbtm/dfp_os/tree/main/app/models"
click node_auth_shell "https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints/auth"
click node_catalog_ops "https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints/products"
click node_finance_ops "https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints/receipts"
click node_production_ops "https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints/print_jobs"
click node_market_ops "https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints/markets"
click node_analytics_api "https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints/api"
click node_trend_scout "https://github.com/iamrbtm/dfp_os/tree/main/app/services/ai/trend_scout"
click node_celery_lane "https://github.com/iamrbtm/dfp_os/blob/main/app/celery_app.py"
click node_migrations "https://github.com/iamrbtm/dfp_os/tree/main/migrations"
click node_audit_service "https://github.com/iamrbtm/dfp_os/tree/main/services/audit-log"
click node_docs_service "https://github.com/iamrbtm/dfp_os/tree/main/services/dfpos-api-docs"

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_app_factory,node_module_registry,node_blueprints_shell,node_services_layer,node_forms_schemas,node_models_layer,node_auth_shell,node_catalog_ops,node_finance_ops,node_production_ops,node_market_ops,node_analytics_api,node_trend_scout toneBlue
class node_celery_lane toneAmber
class node_audit_service,node_docs_service toneMint
class node_persistence,node_migrations,node_redis_bus toneRose
```

## Components

### Main App

Modular Flask monolith

- [App Factory](https://github.com/iamrbtm/dfp_os/blob/main/app/__init__.py): Flask factory · Creates and configures the main Flask application. · `app/__init__.py`
- [Module Registry](https://github.com/iamrbtm/dfp_os/blob/main/app/module_registry.py): governance · Central module metadata, permissions, dependencies, and feature exposure. · `app/module_registry.py`
- [Blueprints](https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints): HTTP routes · User-facing and API entrypoints for the monolith. · `app/blueprints`
- [Services](https://github.com/iamrbtm/dfp_os/tree/main/app/services): domain logic · Business rules, orchestration, and mutations between routes and data. · `app/services`
- [Forms & Schemas](https://github.com/iamrbtm/dfp_os/tree/main/app/forms): validation layer · Flask-WTF forms and API schemas for shaping input and output. · `app/forms`
- [Models](https://github.com/iamrbtm/dfp_os/tree/main/app/models): ORM entities · SQLAlchemy domain models and transactional records. · `app/models`
- [Auth Shell](https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints/auth): login/session · Human authentication, dashboard shell, and API token access. · `app/blueprints/auth`
- [Catalog Ops](https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints/products): merchandise · Customers, products, orders, POS, inventory, and storefront flows. · `app/blueprints/products`
- [Finance Ops](https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints/receipts): receipts/expenses · Receipt intake, approval, expense creation, and financial records. · `app/blueprints/receipts`
- [Production Ops](https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints/print_jobs): workflow · Printers, print jobs, prep tasks, and fulfillment workflow objects. · `app/blueprints/print_jobs`
- [Market Ops](https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints/markets): field ops · Markets, scheduling, logistics, and related operational records. · `app/blueprints/markets`
- [API Layer](https://github.com/iamrbtm/dfp_os/tree/main/app/blueprints/api): JSON API · Code-first JSON API and OpenAPI surface exposed by Flask-Smorest. · `app/blueprints/api`
- [Trend Scout](https://github.com/iamrbtm/dfp_os/tree/main/app/services/ai/trend_scout): AI pipeline · Signal ingestion, scoring, calibration, backtesting, and monitoring for trend opportunities. · `app/services/ai/trend_scout`

### Async Work

Worker and scheduled processing

- [Worker Lane](https://github.com/iamrbtm/dfp_os/blob/main/app/celery_app.py): async jobs · Celery tasks for cost calculation, model analysis, and trend processing. · `app/celery_app.py`

### Deployable Services

Standalone adjacent services

- [Audit Log Service](https://github.com/iamrbtm/dfp_os/tree/main/services/audit-log): FastAPI service · Standalone append-only audit event service with hashing, search, and worker ingestion. · `services/audit-log`
- [API Docs Service](https://github.com/iamrbtm/dfp_os/tree/main/services/dfpos-api-docs): docs renderer · Standalone Redoc service that fetches and renders the main app OpenAPI spec. · `services/dfpos-api-docs`

### Infrastructure

Persistence and external dependencies

- **MariaDB**: primary datastore · Primary relational store for the monolith's operational data.
- [Migrations](https://github.com/iamrbtm/dfp_os/tree/main/migrations): schema evolution · Alembic migration history for the main database. · `migrations`
- **Redis Streams**: event bus · Asynchronous ingestion path used by the audit-log service.

## Connections

- App Factory → Module Registry: loads modules · App startup consults module metadata and feature exposure.
- App Factory → Blueprints: registers · Factory registers HTTP blueprints into the app.
- App Factory → Services: wires · Factory initializes service dependencies and extensions.
- App Factory → Models: binds ORM · Factory configures the SQLAlchemy persistence layer.
- App Factory → API Layer: exposes · Factory enables the code-first API surface.
- Blueprints → Auth Shell: includes · Routes cover login, dashboard, and token-based access.
- Blueprints → Catalog Ops: includes · Routes serve catalog, orders, POS, customers, and storefront flows.
- Blueprints → Finance Ops: includes · Routes handle receipt intake and expense workflows.
- Blueprints → Production Ops: includes · Routes manage printers, print jobs, and prep tasks.
- Blueprints → Market Ops: includes · Routes manage market operations and planning.
- Blueprints → API Layer: mounts · Blueprints expose the JSON API and documentation-related endpoints.
- Blueprints → Services: calls · HTTP handlers delegate business logic to service modules.
- Services → Forms & Schemas: validates · Services shape and validate inputs and outputs through forms and schemas.
- Services → Models: reads/writes · Services persist and query domain objects.
- Services → MariaDB: stores · Business mutations are ultimately written to MariaDB.
- Models → MariaDB: maps to · ORM entities persist into the relational database.
- Migrations → MariaDB: evolves · Alembic tracks and applies schema changes.
- Trend Scout → Worker Lane: offloads · Long-running trend analysis and calibration are executed asynchronously.
- Trend Scout → MariaDB: persists · Trend models, scores, and history are stored in the main database.
- Worker Lane → MariaDB: updates · Worker jobs update operational and analytical records.
- Audit Log Service → Redis Streams: ingests · Audit events can arrive through Redis stream ingestion.
- Audit Log Service → MariaDB: stores · Audit events are written to the service's own database layer.
- API Docs Service → API Layer: fetches spec · Docs service retrieves the OpenAPI document from the main app.
