How iamrbtm/dfp_os works
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: blueprints Blueprints · __init__.py App Factory · services Services · models Models
Components 19
Main App
Modular Flask monolith
- App Factory · Creates and configures the main Flask application.
app/__init__.py - Module Registry · Central module metadata, permissions, dependencies, and feature exposure.
app/module_registry.py - Blueprints · User-facing and API entrypoints for the monolith.
app/blueprints - Services · Business rules, orchestration, and mutations between routes and data.
app/services - Forms & Schemas · Flask-WTF forms and API schemas for shaping input and output.
app/forms - Models · SQLAlchemy domain models and transactional records.
app/models - Auth Shell · Human authentication, dashboard shell, and API token access.
app/blueprints/auth - Catalog Ops · Customers, products, orders, POS, inventory, and storefront flows.
app/blueprints/products - Finance Ops · Receipt intake, approval, expense creation, and financial records.
app/blueprints/receipts - Production Ops · Printers, print jobs, prep tasks, and fulfillment workflow objects.
app/blueprints/print_jobs - Market Ops · Markets, scheduling, logistics, and related operational records.
app/blueprints/markets - API Layer · Code-first JSON API and OpenAPI surface exposed by Flask-Smorest.
app/blueprints/api - Trend Scout · Signal ingestion, scoring, calibration, backtesting, and monitoring for trend opportunities.
app/services/ai/trend_scout
Async Work
Worker and scheduled processing
- Worker Lane · Celery tasks for cost calculation, model analysis, and trend processing.
app/celery_app.py
Deployable Services
Standalone adjacent services
- Audit Log Service · Standalone append-only audit event service with hashing, search, and worker ingestion.
services/audit-log - API Docs Service · Standalone Redoc service that fetches and renders the main app OpenAPI spec.
services/dfpos-api-docs
Infrastructure
Persistence and external dependencies
- MariaDB · Primary relational store for the monolith's operational data.
- Migrations · Alembic migration history for the main database.
migrations - Redis Streams · Asynchronous ingestion path used by the audit-log service.
Connections 23
- 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.