Feature/workflow

backend/app/api/v1/api.py

@@ -1,7 +1,9 @@
 from fastapi import APIRouter
-from app.api.v1.endpoints import states
+from app.api.v1.endpoints import states, workflows
 
 api_router = APIRouter()
 
 # Include all endpoint routers
 api_router.include_router(states.router, prefix="/states", tags=["states"])
+api_router.include_router(
+    workflows.router, prefix="/workflows", tags=["workflows"])

backend/app/api/v1/endpoints/states.py

@@ -1,22 +1,22 @@
 from fastapi import APIRouter, Depends, HTTPException, Query
 from sqlalchemy.orm import Session
-from typing import List
 from app.database import get_db
 from app.schemas.state import StateCreate, StateUpdate, StateResponse
 from app.services.state_service import StateService
 
 router = APIRouter()
 
 
-@router.get("/", response_model=List[StateResponse], summary="Get all states")
+@router.get("/", response_model=list[StateResponse], summary="Get all states")
 async def get_states(
     skip: int = Query(0, ge=0, description="Number of records to skip"),
-    limit: int = Query(100,
-                       ge=1,
-                       le=1000,
-                       description="Maximum number of records to return"
-                       ),
-    db: Session = Depends(get_db)
+    limit: int = Query(
+        100,
+        ge=1,
+        le=1000,
+        description="Maximum number of records to return",
+    ),
+    db: Session = Depends(get_db),
 ):
     """
     Retrieve all states with pagination support, ordered by sort_order.
@@ -27,10 +27,11 @@ async def get_states(
     return states
 
 
-@router.get("/active",
-            response_model=List[StateResponse],
-            summary="Get active states"
-            )
+@router.get(
+    "/active",
+    response_model=list[StateResponse],
+    summary="Get active states",
+)
 async def get_active_states(db: Session = Depends(get_db)):
     """
     Retrieve all active states, ordered by sort_order.
@@ -39,13 +40,14 @@ async def get_active_states(db: Session = Depends(get_db)):
     return states
 
 
-@router.get("/{state_id}",
-            response_model=StateResponse,
-            summary="Get state by ID"
-            )
+@router.get(
+    "/{state_id}",
+    response_model=StateResponse,
+    summary="Get state by ID",
+)
 async def get_state(
     state_id: int,
-    db: Session = Depends(get_db)
+    db: Session = Depends(get_db),
 ):
     """
     Retrieve a specific state by its ID.
@@ -57,14 +59,15 @@ async def get_state(
     return state
 
 
-@router.post("/",
-             response_model=StateResponse,
-             status_code=201,
-             summary="Create new state"
-             )
+@router.post(
+    "/",
+    response_model=StateResponse,
+    status_code=201,
+    summary="Create new state",
+)
 async def create_state(
     state: StateCreate,
-    db: Session = Depends(get_db)
+    db: Session = Depends(get_db),
 ):
     """
     Create a new state.
@@ -77,14 +80,15 @@ async def create_state(
     return StateService.create_state(db, state)
 
 
-@router.put("/{state_id}",
-            response_model=StateResponse,
-            summary="Update state"
-            )
+@router.put(
+    "/{state_id}",
+    response_model=StateResponse,
+    summary="Update state",
+)
 async def update_state(
     state_id: int,
     state_update: StateUpdate,
-    db: Session = Depends(get_db)
+    db: Session = Depends(get_db),
 ):
     """
     Update an existing state.
@@ -98,7 +102,7 @@ async def update_state(
 @router.delete("/{state_id}", summary="Delete state")
 async def delete_state(
     state_id: int,
-    db: Session = Depends(get_db)
+    db: Session = Depends(get_db),
 ):
     """
     Delete a state.
@@ -108,10 +112,11 @@ async def delete_state(
     return {"message": f"State {state_id} deleted successfully"}
 
 
-@router.post("/initialize",
-             response_model=List[StateResponse],
-             summary="Initialize default states"
-             )
+@router.post(
+    "/initialize",
+    response_model=list[StateResponse],
+    summary="Initialize default states",
+)
 async def initialize_default_states(db: Session = Depends(get_db)):
     """
     Initialize default states (New, In Progress, Done) if they don't exist.

backend/app/api/v1/endpoints/workflows.py

@@ -0,0 +1,52 @@
+from fastapi import APIRouter, HTTPException
+
+from app.services.workflow_service import WorkflowService
+from app.schemas.workflow import StartWorkflowRequest, CompleteTaskRequest
+
+
+router = APIRouter()
+
+
+
+
+
+@router.post("/start", summary="Start a new workflow instance")
+async def start_workflow(payload: StartWorkflowRequest):
+    try:
+        return WorkflowService.start_workflow(
+            name=payload.name,
+            bpmn_filename=payload.bpmn_filename,
+            process_id=payload.process_id,
+        )
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail="BPMN file not found")
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.get("/", summary="List workflow instances")
+async def list_workflows():
+    return WorkflowService.list_workflows()
+
+
+@router.post(
+    "/{instance_id}/tasks/{task_id}/complete",
+    summary="Complete a user task",
+)
+async def complete_task(
+    instance_id: str,
+    task_id: str,
+    payload: CompleteTaskRequest,
+):
+    try:
+        return WorkflowService.complete_user_task(
+            instance_id,
+            task_id,
+            payload.data.model_dump(),
+        )
+    except KeyError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    except Exception as exc:
+        raise HTTPException(status_code=500, detail=str(exc))

backend/app/schemas/__init__.py

@@ -1 +1 @@
-# Schemas Package
+ 

backend/app/schemas/state.py

@@ -1,5 +1,4 @@
 from pydantic import BaseModel, Field, ConfigDict, field_serializer
-from typing import Optional
 from datetime import datetime
 
 
@@ -13,10 +12,10 @@ class StateBase(CustomBaseModel):
                       max_length=50,
                       description="State name"
                       )
-    description: Optional[str] = Field(None,
-                                       max_length=200,
-                                       description="State description"
-                                       )
+    description: str | None = Field(None,
+                                    max_length=200,
+                                    description="State description"
+                                    )
     is_active: bool = Field(True, description="Whether the state is active")
     sort_order: int = Field(0, ge=0, description="Sort order for display")
 
@@ -26,17 +25,17 @@ class StateCreate(StateBase):
 
 
 class StateUpdate(CustomBaseModel):
-    name: Optional[str] = Field(None, min_length=1, max_length=50)
-    description: Optional[str] = Field(None, max_length=200)
-    is_active: Optional[bool] = None
-    sort_order: Optional[int] = Field(None, ge=0)
+    name: str | None = Field(None, min_length=1, max_length=50)
+    description: str | None = Field(None, max_length=200)
+    is_active: bool | None = None
+    sort_order: int | None = Field(None, ge=0)
 
 
 class StateResponse(StateBase):
     id: int
     created_at: datetime
-    updated_at: Optional[datetime] = None
+    updated_at: datetime | None = None
 
     @field_serializer("created_at", "updated_at", when_used="json")
-    def serialize_dt(self, dt: Optional[datetime]) -> Optional[str]:
+    def serialize_dt(self, dt: datetime | None) -> str | None:
         return dt.isoformat() if dt else None

backend/app/schemas/workflow.py

@@ -0,0 +1,15 @@
+from pydantic import BaseModel, Field
+
+
+class StartWorkflowRequest(BaseModel):
+    name: str = Field(default="Simple Approval")
+    bpmn_filename: str = Field(default="simple_approval.bpmn")
+    process_id: str = Field(default="SimpleApproval")
+
+
+class CompleteTaskRequest(BaseModel):
+    class ApprovalData(BaseModel):
+        approved: bool
+
+    data: ApprovalData
+

backend/app/services/state_service.py

@@ -1,17 +1,17 @@
 from sqlalchemy.orm import Session
 from sqlalchemy.exc import IntegrityError
-from typing import List, Optional
 from app.models.state import State
 from app.schemas.state import StateCreate, StateUpdate
 from fastapi import HTTPException
 
 
 class StateService:
     @staticmethod
-    def get_states(db: Session,
-                   skip: int = 0,
-                   limit: int = 100
-                   ) -> List[State]:
+    def get_states(
+        db: Session,
+        skip: int = 0,
+        limit: int = 100,
+    ) -> list[State]:
         """Get all states with pagination, ordered by sort_order"""
         return (
             db.query(State)
@@ -22,17 +22,17 @@ def get_states(db: Session,
         )
 
     @staticmethod
-    def get_state_by_id(db: Session, state_id: int) -> Optional[State]:
+    def get_state_by_id(db: Session, state_id: int) -> State | None:
         """Get state by ID"""
         return db.query(State).filter(State.id == state_id).first()
 
     @staticmethod
-    def get_state_by_name(db: Session, name: str) -> Optional[State]:
+    def get_state_by_name(db: Session, name: str) -> State | None:
         """Get state by name"""
         return db.query(State).filter(State.name == name).first()
 
     @staticmethod
-    def get_active_states(db: Session) -> List[State]:
+    def get_active_states(db: Session) -> list[State]:
         """Get all active states, ordered by sort_order"""
         return (
             db.query(State)
@@ -65,10 +65,11 @@ def create_state(db: Session, state: StateCreate) -> State:
             )
 
     @staticmethod
-    def update_state(db: Session,
-                     state_id: int,
-                     state_update: StateUpdate
-                     ) -> State:
+    def update_state(
+        db: Session,
+        state_id: int,
+        state_update: StateUpdate,
+    ) -> State:
         """Update an existing state"""
         db_state = StateService.get_state_by_id(db, state_id)
         if not db_state:
@@ -117,7 +118,7 @@ def delete_state(db: Session, state_id: int) -> bool:
             )
 
     @staticmethod
-    def initialize_default_states(db: Session) -> List[State]:
+    def initialize_default_states(db: Session) -> list[State]:
         """Initialize default states if they don't exist"""
         default_states = [
             {"name": "New",