Flowbit Specs

Flowbit – Agent Skill

1. Source of truth

• Always read all files under /specs before writing or modifying any code.
• Treat /specs as the single source of truth.
• If code conflicts with specs, update the code, not the specs (unless explicitly instructed).

2. Product definition

Flowbit is an Operations OS for SMEs, not an ERP and not an accounting system.

Flowbit manages:

• Projects (sales/orders)
• Branching workflows using stages (areas) and dependencies
• Deadlines per stage and project-level timelines (planned vs actual)
• Unit quantity tracking per stage (qty_required, qty_done)
• Visual finance using income/cost events (no formal accounting)
• Products with BOM (materials per unit) and project-level editable snapshots

Out of scope:

• Formal accounting (PUC, taxes, invoices)
• Payroll
• Complex inventory or reservations
• Automated notifications
• Over-engineered abstractions

3. Architecture & stack

Backend

• FastAPI
• SQLAlchemy
• Pydantic
• PostgreSQL
• Multi-tenant architecture: every entity is scoped by company_id

Frontend

• React + TypeScript
• Vite
• Tailwind CSS
• shadcn/ui components (Radix-based)
• Icons from lucide-react

4. UI rules (very important)

• Build a real SaaS dashboard, not a demo or toy UI.
• Use sidebar + top header layout.
• Prefer Card, Table, Tabs, Badge, Button, Dialog from shadcn/ui.
• Avoid raw <div>-only layouts.
• Avoid inline styles.
• Pages must look production-ready and consistent.

5. Roles & permissions

Roles:

• SUPER_ADMIN: platform owner (can create companies).
• COMPANY_ADMIN (Boss): full access inside a company, including finance.
• STAGE_WORKER: access only to assigned stages.

Rules:

• Finance data is visible only to COMPANY_ADMIN.
• STAGE_WORKER users must never see:
  • prices
  • margins
  • income or cost events
• Stage access is mandatory to view or edit a ProjectStage.

6. Workflow rules (branching)

• Projects select which stages apply.
• Stages have dependencies (edges) that define prerequisites.
• Stage statuses:
  • BLOCKED
  • READY
  • IN_PROGRESS
  • DONE
  • SKIPPED
• A stage becomes READY only when all selected prerequisites are DONE or SKIPPED.
• When a stage becomes DONE, dependent stages must be re-evaluated.

7. Deadlines & timeline

Each ProjectStage tracks:

• planned_due_date
• actual_ready_at
• actual_started_at
• actual_done_at

Timeline rules:

• Show planned vs actual per stage.
• Delays must be computable from stored timestamps.
• Timers are optional but supported.

8. BOM & materials

• Product BOM defines materials per unit.
• On project creation, generate project material requirement snapshots:
  • quantities per unit
  • total quantities
• Project material requirements are editable.
• Editing project requirements must not modify the product BOM.

9. Finance (visual only)

• Financial events are simple records:
  • type: INCOME or COST
  • amount
  • date
  • category
• No accounting logic, no double entry, no taxes.
• Metrics:
  • total income per project
  • total cost per project
  • margin = income − cost

10. Development philosophy

• MVP first. Do not build future features prematurely.
• Prefer clarity over cleverness.
• Avoid over-abstraction.
• Code should look production-ready, not tutorial code.

11. When in doubt

If a requirement is unclear:

1. Check /specs.
2. If still unclear, ask before implementing.