Flow Forge Backend (FastAPI)

Flow Forge is a lightweight project management backend inspired by tools like Azure Boards. It allows managing projects (called Forges), epics (Blueprints), stories (Modules), tasks/bugs (Actions), and iteration-based dashboards with drag-and-drop support for task statuses.

---

🚀 Tech Stack

• Backend Framework: FastAPI
• ORM: SQLAlchemy
• Migrations: Alembic
• Database: PostgreSQL
• Testing: Pytest / FastAPI TestClient

---

📁 Folder Structure

app/
├── main.py
├── db/
│   └── base.py
├── models/
├── schemas/
├── routers/
├── core/
└── utils/

---

✅ Implementation Checklist

🏗️ Initial Setup

Set up project folder structure (`app/`, `models/`, `schemas/`, `routers/`, `db/`, etc.)

Create and activate virtual environment

Install dependencies: `fastapi`, `uvicorn[standard]`, `sqlalchemy`, `alembic`, `pydantic`, `psycopg2-binary`, `python-dotenv`

Initialize Git and `.gitignore`

Create `main.py` and include API routers

Set up `.env` file for DB config

Add CORS middleware

Configure PostgreSQL and Alembic

Create SQLAlchemy base model in `db/base.py`

🧱 Forge (Project)

Create `Forge` model

Create schemas: `ForgeCreate`, `ForgeUpdate`, `ForgeOut`

Implement endpoints:

GET /forges

POST /forges

GET /forges/{forge_id}

PUT /forges/{forge_id}

DELETE /forges/{forge_id}

Add `routers/forges.py`

Write tests

📘 Blueprint (Epic)

Create `Blueprint` model (FK to Forge)

Create schemas: `BlueprintCreate`, `BlueprintUpdate`, `BlueprintOut`

Implement endpoints:

GET /forges/{forge_id}/blueprints

POST /forges/{forge_id}/blueprints

PUT /blueprints/{blueprint_id}

DELETE /blueprints/{blueprint_id}

📦 Module (Story)

Create `Module` model (FK to Blueprint)

Create schemas: `ModuleCreate`, `ModuleUpdate`, `ModuleOut`

Implement endpoints:

GET /blueprints/{blueprint_id}/modules

POST /blueprints/{blueprint_id}/modules

PUT /modules/{module_id}

DELETE /modules/{module_id}

⚙️ Action (Task / Glitch)

Create `Action` model (FK to Module)

Add enum: `ActionType` (`task`, `glitch`)

Add enum: `ActionStatus` (`queued`, `forging`, `jammed`, `crafted`)

Create schemas: `ActionCreate`, `ActionUpdate`, `ActionOut`

Implement endpoints:

GET /modules/{module_id}/actions

POST /modules/{module_id}/actions

PUT /actions/{action_id}

DELETE /actions/{action_id}

PATCH /actions/{action_id}/status

⏳ Iteration

Create `Iteration` model (FK to Forge)

Add `iteration_id` field to `Action`

Create schemas: `IterationCreate`, `IterationUpdate`, `IterationOut`

Implement endpoints:

GET /forges/{forge_id}/iterations

POST /forges/{forge_id}/iterations

PUT /iterations/{iteration_id}

DELETE /iterations/{iteration_id}

GET /iterations/{iteration_id}/actions

📥 Drag & Drop Logic (Kanban)

Implement `PATCH /actions/{action_id}/status`

(Optional) Validate transitions (`queued → forging → crafted`)

(Optional) Add audit log for status changes

Implement dashboard query for iteration with grouped statuses

🧪 Testing & QA

Use `pytest` or FastAPI `TestClient`

Test all endpoints with valid and invalid inputs

Seed sample data for dashboards

Use Swagger UI to test all routes

🧭 Final Touches

Create `.env.example`

Write `README.md` with setup guide and API overview

(Optional) Add code formatter/linter (black, isort, flake8)

(Optional) Add pre-commit hooks

---

🛠️ Future Add-ons

User registration/login (JWT)

Notifications system

Role-based access (admin, contributor)

Export/Import Forge data

---

📚 Terminology Map

Concept	Name in Flow Forge
Project	Forge
Epic	Blueprint
Story	Module
Task / Bug	Action (type: task / glitch)
To Do	Queued
In Progress	Forging
Blocked	Jammed
Completed	Crafted

---

📞 Contact

Want to collaborate or need help setting this up? Reach out to the maintainer.

---

Happy Forging! 🔨