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.