TaskFlow

DDD-Compliant Go Workflow Backend with Hardened State Machine

English | 简体中文

---

Introduction

TaskFlow is a production-grade blueprint for task collaboration and lifecycle management. It prioritizes explicit state transitions, repository-based persistence abstractions, and low-friction developer recovery. By decoupling business logic from infrastructure, it scales from simple task tracking to complex, multi-actor workflows.

Important

This system treats task lifecycles as a formal state machine. Every action (assign, start, submit, approve) is validated against current state and actor permissions to ensure zero illegal transitions.

Note

Current runtime baseline includes password-based registration, POST /auth/login, POST /auth/refresh, password reset, account disable, JWT-only production auth, request/trace IDs, optional OTLP tracing, structured JSON logs, /health + /livez + /readyz + /metrics, versioned Mongo migrations, soft delete with audit retention, and Mongo-backed shared rate limiting / idempotency when running with the Mongo driver.

---

Workflow Architecture

The core engine enforces a strict lifecycle: create -> assign -> start -> submit -> approve/reject -> close.

graph LR
    Create([Create]) --> Assign[Assign]
    Assign --> Start[Start]
    Start --> Submit[Submit]
    Submit --> Review{Review}
    Review -- Reject --> Start
    Review -- Approve --> Close([Close])
    
    style Review fill:none,stroke:#000,stroke-width:2px

Loading

---

Technical Specifications

Domain-Driven Design (DDD) Structure

taskflow/
├── cmd/                # Entry points (HTTP Server)
├── internal/
│   ├── bootstrap/      # Dependency Injection & App Assembly
│   ├── service/        # Hardened State Machine & Business Rules
│   ├── repository/     # Persistence Abstractions (Mongo/Memory)
│   └── domain/         # Core Entities & Value Objects
├── docs/               # Boundary definitions and targets
└── scripts/            # Deployment and utility scripts

Dual-Persistence Driver Protocol

TaskFlow supports pluggable persistence through the Repository Pattern:

• Memory Driver: Optimized for lightning-fast local iteration and CI/CD testing.
• Mongo Driver: For production-grade persistence-path validation and horizontal scaling.
• Switching: Controlled via TASK_REPOSITORY_DRIVER environment variable without business logic changes.

Enterprise Installation & Usage

Prerequisites

• Go 1.26.4 or higher
• MongoDB (optional, for production driver)

Quick Start

# Clone the repository
git clone https://github.com/AsaqeLee/taskflow.git
cd taskflow

# Verify integrity
go test ./...

# Run local dev mode (enables seeded dev users and X-User-ID / legacy token fallback)
DEV_MODE=true TASK_REPOSITORY_DRIVER=memory JWT_SECRET=change-me go run ./cmd/server

# Register a password-based user
curl -X POST http://localhost:8080/users \
  -H 'Content-Type: application/json' \
  -d '{"id":"u_demo","name":"Demo User","role":"human","password":"strong-pass-123"}'

# Or login with an existing user
curl -X POST http://localhost:8080/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"id":"u_demo","password":"strong-pass-123"}'

# Rotate a refresh token
curl -X POST http://localhost:8080/auth/refresh \
  -H 'Content-Type: application/json' \
  -d '{"refresh_token":"<refresh-token>"}'

---

Strategic Boundaries

• Audit Traceability: Every state change triggers an AuditLog for professional accountability.
• Built-In Account Baseline: Password login, refresh tokens, password reset, and disable flows are built in; SSO / OAuth remains an integration-layer concern.
• Clean Code: Adheres to high-integrity Go standards with minimal third-party dependency bloat.

---

© 2026 AsaqeLee. Built for deterministic workflow orchestration.