Fabric IQ Doc 1 — Code & Flow Explainer (FactoryTracking today)

0. Two-line summary

FactoryTracking is a multi-tenant garment shop-floor app: each factory is a companies row, and every lot is a production_batches row that moves CUTTING → DISPATCH with QR scans and qty handshakes. It also covers thin inventory/BOM, orders, buyer portal, defects, AI assist, and soft Stripe/Paytm billing — strong as a pilot MES, not yet production-SaaS.

1. What the product does (detailed)

1.1 Industry context

Indian garment / fabric factories run work as lots or batches through departments (cutting, stitching, washing, QC, packing, dispatch). Visibility gaps cause missing pieces, late deliveries, and phone-call chaos between floor and office.

1.2 What this code solves today

• Track every batch through six fixed stages with who moved what quantity.
• QR labels so a phone can prove a batch was seen on the floor (scan_logs).
• Quantity integrity: sending dept enters sent_qty; receiving dept enters received_qty; mismatch → ALERT.
• Multi-tenant SaaS shell: signup creates a company + admin; data isolated by company_id.
• Materials: inventory ledger + style BOM + WhatsApp reorder draft links (wa.me).
• Commercial thin layer: customer orders, buyer login, defects, reports, optional AI chat/ML delay/qty models.
• Billing UI: 14-day trial + Stripe/Paytm hooks (soft gate — expired trial still gets full app access).

1.3 What it does not do (preview — full gaps in Doc 2)

No live confirmed cloud deploy, no real WhatsApp bot, no GST invoices, no formal POs/MRP, no fabric roll/shade tracking, no hard subscription lockout.

2. Tech stack & file map

Two-line summary

Almost all behavior lives in one Flask file (app.py); SQLite is default; Postgres is an optional shim via db.py that has not been proven in production.

Stack

Key files

Runtime config (env)

3. Multi-tenancy & security model

Two-line summary

Every business row carries company_id; the logged-in session’s company_id is applied to queries so factories cannot see each other. Usernames are globally unique so login never asks “which factory?”

Detailed rules

1. **Tenant = companies row.** Signup inserts company (plan=trial, subscription_status=trialing, trial_ends_at=+14d) + first user (Administrator, dept PRODUCTION).
2. Session keys (staff): user, name, department, role, company_id.
3. Session keys (buyer portal — separate): buyer_id, buyer_company_id, buyer_name, buyer_username.
4. Roles: Administrator (full), Supervisor (move/receive any stage), Operator / Inspector (only if session.department == batch.current_stage).
5. Subscription soft gate: subscription_active() is used on billing UX / emails — not a global before_request lock. Expired trials still use MES.
6. Login rate limit: ~5 fails / 60s in-memory.
7. Password reset: token in password_resets; requires SMTP or admin reset from Users page.

flowchart TD
  signup["POST signup"] --> co["Insert companies"]
  co --> u["Insert admin user"]
  u --> sess["Set session company_id"]
  sess --> onboard["Onboarding checklist"]
  login["POST login"] --> lookup["Find user by username"]
  lookup --> check["Check password hash"]
  check --> sess2["Session with company_id"]
  sess2 --> home["Home dashboard"]

4. Complete database schema

Two-line summary

Live demo DB has 29 user tables (plus sqlite_sequence). Core MES tables are created in create_database.py; many later features are created at runtime by ensure_* in app.py.

4.1 Entity relationship (logical)

erDiagram
  companies ||--o{ users : has
  companies ||--o{ production_batches : has
  companies ||--o{ factory_stages : has
  companies ||--o{ inventory_items : has
  companies ||--o{ customer_orders : has
  companies ||--o{ buyers : has
  production_batches ||--o{ movement_history : moves
  production_batches ||--o{ scan_logs : scans
  production_batches ||--o{ defect_records : defects
  production_batches ||--o{ batch_sizes : sizes
  production_batches }o--o{ customer_orders : linked_by_order_id
  inventory_items ||--o{ inventory_transactions : ledger
  inventory_items ||--o{ bill_of_materials : bom
  suppliers ||--o{ purchase_requests : requests

4.2 Identity & access tables

companies — tenant / factory

Two-line: One row per paying (or trial) factory. Holds plan, Stripe IDs, trial end, and active flag.

Demo rows: 1 (Demo Factory).

users — factory staff

Two-line: Login accounts scoped to one company; username unique globally; department drives stage permissions.

Demo rows: 10.

buyers — brand / customer portal users

Two-line: Separate login for external buyers; visibility filtered by matching customer_name on orders.

Demo rows: 1.

password_resets

Two-line: One-time tokens for forgot-password; expire and single-use.

4.3 Production / MES tables

factory_stages — per-tenant pipeline

Two-line: Ordered list of stage keys for this factory; defaults to the six garment stages.

Default keys: CUTTING, STITCHING, WASHING, QC, PACKING, DISPATCH.

production_batches — core lot (most important table)

Two-line: One garment lot’s identity, per-stage quantities, current stage, qty handshake fields, AI fields, QR path, optional order link.

Demo rows: 200.

batch_sizes

Two-line: Flexible size breakdown (S/M/L/…) instead of only size_28…38 columns.

batch_stage_quantities

Two-line: Flexible stage qty mirror keyed by stage_key (future-proof vs fixed cut_qty columns).

movement_history

Two-line: Audit of every stage transition with quantity and who moved it.

scan_logs

Two-line: QR presence events; does not by itself advance stage.

activity_logs

Two-line: General audit trail (MOVE_BATCH, login-ish actions, etc.).

daily_targets

Two-line: Per-day, per-stage target quantity for ops dashboards.

department_performance

Two-line: Cached KPIs per department (efficiency, rejects).

dashboard_summary

Two-line: One cached home-dashboard snapshot per company (stage totals).

test_logs

Two-line: Ad-hoc factory test records attached to a batch/department.

4.4 Inventory & materials tables

inventory_items

Two-line: SKU catalogue (fabric, trims, etc.) with reorder level and optional supplier link.

inventory_transactions

Two-line: Ledger of stock movements; on-hand is sum of IN − OUT (− RESERVED logic in app).

bill_of_materials

Two-line: Per-style material recipe: how much of each item per finished piece.

suppliers

Two-line: Supplier directory for reorders.

purchase_requests

Two-line: Log of reorder messages sent/drafted (channel default whatsapp).

packing_lists

Two-line: Material “production orders” — planned reservation of inventory against a style/qty (status Planned / Reserved / Short).

packing_list_items

Two-line: Line items of materials required/reserved for a packing_list.

packing_sheets

Two-line: Header for style×size packing grids (carton/size export) — naming overlaps “packing” but is separate from material lists.

packing_sheet_items

Two-line: Grid cells: row label × size label × quantity.

stage_labor_rates

Two-line: Cost-per-piece by stage for cost reports.

4.5 Orders, quality, billing tables

customer_orders

Two-line: Buyer/brand order header; status drives commercial visibility; can link to batches via order_id.

defect_records

Two-line: Typed QC (or any-stage) defects — why pieces failed, separate from qty mismatch ALERT.

Defect types: Stitch Issue, Wrong Size, Broken Zip, Loose Button, Fabric Defect, Color Mismatch, Print Defect, Measurement Issue, Other.

pending_orders

Two-line: Paytm checkout pending rows for SaaS subscription payment (not garment customer orders).

5. End-to-end flows (detailed)

5.1 Shop-floor production (the heart)

Two-line summary

Create a batch at CUTTING → print/scan QR → move to next stage with quantity → receiving department confirms → repeat until DISPATCH; QC can log typed defects along the way.

Detailed steps

1. Admin/supervisor opens /create-batch, enters style (fit), quantities, optional sizes / line / order link.
2. App inserts production_batches with current_stage=CUTTING, sets cut_qty, may write batch_sizes.
3. Optional BOM consume may reduce inventory when cutting starts (style-matched bill_of_materials).
4. Open /batch/<id> → /qr/<id> generates PNG under static/qr_codes/{company_id}_{batch_id}.png encoding the batch id string.
5. Floor phone camera (html5-qrcode) hits /log-scan?batch=BATCH-… → scan_logs (duplicate window ~30s). Scan ≠ move.
6. Sending operator POST /move/<batch_id> with quantity → validates against previous stage qty, updates current_stage, stage qty column, sent_qty, inserts movement_history, activity log, may refresh AI fields.
7. Receiving operator POST /receive/<batch_id> with received qty → received_qty, difference_qty, movement_status OK/ALERT.
8. Permissions: Admin/Supervisor any stage; others only if department matches current stage.
9. At QC (or any stage), POST /batch/<id>/defect writes defect_records.
10. Packing sheets optional via /packing-list/*.
11. Final stage DISPATCH; dashboards count it completed; reports/TV/command-center read aggregates.

flowchart TD
  A["Create batch at CUTTING"] --> B["Generate QR"]
  B --> C["Scan log presence"]
  C --> D["Move with sent qty"]
  D --> E["Receive with received qty"]
  E --> F{"Qty matches?"}
  F -->|yes| G[OK]
  F -->|no| H[ALERT]
  G --> I{"More stages?"}
  H --> I
  I -->|yes| D
  I -->|QC| J["Log defects"]
  J --> I
  I -->|DISPATCH| K["Reports and TV"]

Tables touched

production_batches, batch_sizes, batch_stage_quantities, movement_history, scan_logs, activity_logs, defect_records, optionally inventory_transactions, bill_of_materials.

Routes

/create-batch, /production, /move/<id>, /receive/<id>, /batch/<id>, /qr/<id>, /log-scan, /scan-history, /timeline/<id>, /quantity-alerts, /department/<dept>.

5.2 Signup → trial → first users

Two-line summary

Factory owner signs up → company + admin created with 14-day trial → onboarding checklist → admin adds floor users by department.

Detailed steps

1. GET/POST /signup (company name, full name, username, password ≥8).
2. Insert companies + users Administrator.
3. Session set; redirect /onboarding.
4. ensure_factory_stages_table seeds six stages for company when used.
5. Admin /users/add creates cutting1, stitch1, etc.
6. Billing page shows trial countdown; payment optional until you enforce hard gate in Fabric IQ.

5.3 Customer order → batch → buyer portal

Two-line summary

Staff create an order, link one or more batches, update status through production; buyer logs in and only sees orders matching their customer_name.

flowchart LR
  O["Add order Pending"] --> L["Link batch"]
  L --> P["Floor MES"]
  P --> S["Ready or Dispatched"]
  B["Create buyer login"] --> V["Buyer portal"]
  S --> V

Statuses: Pending → In Production → Ready → Dispatched.

Routes: /orders*, /buyers*, /buyer/login, /buyer/, /buyer/order/<id>.

5.4 Inventory → low stock → WhatsApp draft

Two-line summary

Stock is ledger-based; when on-hand ≤ reorder level, admin drafts a WhatsApp message via wa.me/91… and may log purchase_requests. There is no automated Meta Cloud send in this codebase.

flowchart TD
  item["Inventory item"] --> txn["IN OUT RESERVED ledger"]
  item --> bom["Style BOM"]
  bom --> reserve["Production order reserve"]
  txn --> low{"On hand at or below reorder?"}
  low -->|yes| draft["Open wa.me draft"]
  draft --> log["Log purchase_requests"]

Detailed: add item → IN/OUT movements → BOM for style → production-orders reserve materials → low stock UI + /inventory/reorder-message/<id> → optional daily email job via /internal/tasks/daily-notifications.

5.5 Defects vs quantity ALERT

Two-line summary

ALERT = pieces went missing between send and receive. Defects = pieces failed quality with a typed reason. Both can exist on the same batch.

5.6 Billing (SaaS) as coded today

Two-line summary

Trial starts at signup; /billing shows Stripe Checkout and/or Paytm; webhooks/callbacks set subscription_status=active — but MES routes are not blocked when trial expires.

sequenceDiagram
  participant U as Admin
  participant App as FlaskApp
  participant Pay as StripeOrPaytm
  U->>App: Open billing page
  U->>App: Start checkout
  App->>Pay: Create payment session
  Pay->>App: Webhook or callback
  App->>App: Set subscription active
  Note over App: Soft gate only MES still open if expired

5.7 AI flows

Two-line summary

Pickled sklearn models score quantity anomalies and delay risk on move/receive; optional OpenRouter chat answers questions with tool calls over tenant data (rate-limited).

Routes: /ai-report, /ai-briefing, /ai-chat, /ai-chat/ask, /api/prediction/<batch_id>.

6. Route map (grouped)

Two-line summary

~103 routes in app.py: auth, MES, inventory, orders/buyers, packing, defects, reports, AI, billing, import, internal cron.

7. Demo data snapshot (local DB)

Floor seed passwords: operators use 123; admin uses admin123.

8. Deployment status (today)

Two-line summary

No confirmed live public deployment from this tree. Render/OCI docs exist but filenames (render .yaml, requirements .txt) and missing .github/workflows/ placement mean templates would fail as-is.

Treat FactoryTracking as local/demo reference for Fabric IQ domain logic.

9. How to run locally

cd FactoryTracking
source .venv/bin/activate   # Python 3.12 venv
# .env: PORT=5050, FACTORY_DEMO_MODE=1, FACTORY_DEBUG=1, empty DATABASE_URL
python app.py
# open http://localhost:5050  → admin / admin123

Warning: python create_database.py wipes the SQLite file and reseeds demo data.

10. What to remember before Fabric IQ

1. Domain logic (stages, move/receive, QR, company_id) is the valuable part — keep it.
2. Monolith + SQLite + soft billing + unwired WhatsApp are why we rebuild.
3. Every table/column above must have a Postgres equivalent (or intentional redesign) in Fabric IQ schema.
4. Next: 02 Gaps & additions · 03 Fabric IQ plan