TaskFlow Architect

A modern, clean-architecture approach to task management built with Python and FastAPI

🎯 Overview

TaskFlow Architect is a production-ready task management system that demonstrates modern software architecture principles. Built with Python and FastAPI, it showcases clean architecture, domain-driven design, and SOLID principles in a practical, real-world application.

Key Features

RESTful API with comprehensive documentation
Clean Architecture implementation
Domain-Driven Design patterns
Asynchronous operations
Type safety with Python type hints
Comprehensive logging system
In-memory repository with easy database integration
Detailed API documentation with examples

🏗️ Architecture

The project follows Clean Architecture principles, organized in distinct layers:

taskflow_architect/
├── src/
│   ├── domain/          # Business logic and rules
│   ├── application/     # Use cases and DTOs
│   └── infrastructure/  # External interfaces
└── tests/              # Test suites

Domain Layer

Core business logic
Business rules and validations
Entity definitions
Repository interfaces

Application Layer

Use case implementations
DTOs (Data Transfer Objects)
Service orchestration
Business workflows

Infrastructure Layer

FastAPI implementation
Repository implementations
Logging system
External service integrations

🛠️ Technical Stack

Python 3.9+: Modern Python features and type hints
FastAPI: High-performance web framework
Pydantic: Data validation using Python type annotations
pytest: Testing framework
uvicorn: ASGI server implementation
Python Logging: Built-in logging system

📦 Installation

Clone the repository:

git clone https://github.com/yourusername/taskflow-architect.git
cd taskflow-architect

Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

🚀 Usage

VS Code Setup

Install recommended VS Code extensions:

{
    "recommendations": [
        "ms-python.python",                  // Python language support
        "ms-python.vscode-pylance",          // Python type checking
        "ms-python.black-formatter",         // Code formatting
        "njpwerner.autodocstring",           // Python docstring generation
        "kevinrose.vsc-python-indent",       // Smart Python indentation
        "littlefoxteam.vscode-python-test-adapter",  // Test Explorer UI
        "visualstudioexptteam.vscodeintellicode",    // AI-assisted development
        "christian-kohler.path-intellisense",        // Path autocompletion
        "aaron-bond.better-comments",                // Comment highlighting
        "ryanluker.vscode-coverage-gutters",        // Code coverage highlighting
        "yzhang.markdown-all-in-one",               // Markdown support
        "bierner.markdown-preview-github-styles",    // GitHub-style markdown
        "esbenp.prettier-vscode",                    // General code formatting
        "shardulm94.trailing-spaces",               // Highlight trailing spaces
        "streetsidesoftware.code-spell-checker"     // Spell checking
    ]
}

Create .vscode/tasks.json for common operations:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Start FastAPI Server",
            "type": "shell",
            "command": "${command:python.interpreterPath}",
            "args": [
                "-m",
                "uvicorn",
                "src.main:app",
                "--reload",
                "--port",
                "8000"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "presentation": {
                "reveal": "always",
                "panel": "new"
            }
        },
        {
            "label": "Run Tests",
            "type": "shell",
            "command": "${command:python.interpreterPath}",
            "args": [
                "-m",
                "pytest",
                "tests/",
                "-v"
            ],
            "group": "test",
            "presentation": {
                "reveal": "always",
                "panel": "new"
            }
        },
        {
            "label": "Run Tests with Coverage",
            "type": "shell",
            "command": "${command:python.interpreterPath}",
            "args": [
                "-m",
                "pytest",
                "tests/",
                "--cov=src",
                "--cov-report=html"
            ],
            "group": "test",
            "presentation": {
                "reveal": "always",
                "panel": "new"
            }
        },
        {
            "label": "Format Code",
            "type": "shell",
            "command": "${command:python.interpreterPath}",
            "args": [
                "-m",
                "black",
                "src/",
                "tests/"
            ],
            "group": "build"
        },
        {
            "label": "Install Dependencies",
            "type": "shell",
            "command": "${command:python.interpreterPath}",
            "args": [
                "-m",
                "pip",
                "install",
                "-r",
                "requirements.txt"
            ],
            "group": "none"
        }
    ]
}

Create .vscode/snippets/python.json for code snippets:

{
    "FastAPI Route": {
        "prefix": "route",
        "body": [
            "@router.${1|get,post,put,patch,delete|}(",
            "    \"/${2:path}\",",
            "    response_model=${3:ResponseModel},",
            "    summary=\"${4:Summary}\",",
            "    response_description=\"${5:Response description}\"",
            ")",
            "async def ${6:function_name}(",
            "    ${7:parameters}",
            ") -> ${8:ReturnType}:",
            "    \"\"\"",
            "    ${9:Function description}",
            "    \"\"\"",
            "    try:",
            "        ${0:pass}",
            "    except Exception as error:",
            "        raise HTTPException(",
            "            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,",
            "            detail=str(error)",
            "        )"
        ],
        "description": "Create a FastAPI route"
    },
    "Domain Entity": {
        "prefix": "entity",
        "body": [
            "@dataclass",
            "class ${1:EntityName}:",
            "    \"\"\"",
            "    ${2:Entity description}",
            "    \"\"\"",
            "    id: UUID",
            "    ${3:field_name}: ${4:type}",
            "    created_at: datetime",
            "    updated_at: datetime",
            "",
            "    @classmethod",
            "    def create(cls, ${5:parameters}) -> \"${1:EntityName}\":",
            "        now = datetime.utcnow()",
            "        return cls(",
            "            id=uuid4(),",
            "            ${6:field_assignments},",
            "            created_at=now,",
            "            updated_at=now",
            "        )",
            "",
            "    def update(self, ${7:parameters}) -> None:",
            "        ${0:pass}"
        ],
        "description": "Create a domain entity"
    },
    "Repository Interface": {
        "prefix": "repo",
        "body": [
            "class ${1:EntityName}Repository(ABC):",
            "    @abstractmethod",
            "    async def save(self, ${2:entity}: ${3:EntityType}) -> None:",
            "        pass",
            "",
            "    @abstractmethod",
            "    async def find_by_id(self, id: UUID) -> Optional[${3:EntityType}]:",
            "        pass",
            "",
            "    @abstractmethod",
            "    async def find_all(self) -> List[${3:EntityType}]:",
            "        pass",
            "",
            "    @abstractmethod",
            "    async def delete(self, id: UUID) -> None:",
            "        pass$0"
        ],
        "description": "Create a repository interface"
    },
    "Service Class": {
        "prefix": "service",
        "body": [
            "class ${1:Name}Service:",
            "    def __init__(self, repository: ${2:RepositoryType}):",
            "        self.repository = repository",
            "",
            "    async def create_${3:entity}(self, ${4:parameters}) -> ${5:ReturnType}:",
            "        try:",
            "            ${0:pass}",
            "        except Exception as error:",
            "            raise ValueError(str(error))"
        ],
        "description": "Create a service class"
    },
    "Test Function": {
        "prefix": "test",
        "body": [
            "@pytest.mark.asyncio",
            "async def test_${1:function_name}():",
            "    # Arrange",
            "    ${2:arrangement}",
            "",
            "    # Act",
            "    ${3:action}",
            "",
            "    # Assert",
            "    ${0:assertion}"
        ],
        "description": "Create a test function"
    }
}

Create .vscode/settings.json:

{
    "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
    "python.testing.pytestEnabled": true,
    "python.testing.unittestEnabled": false,
    "python.testing.nosetestsEnabled": false,
    "python.testing.pytestArgs": [
        "tests"
    ],
    "python.formatting.provider": "black",
    "editor.formatOnSave": true,
    "[python]": {
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.organizeImports": true
        }
    }
}

Create .vscode/launch.json for debugging:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: FastAPI",
            "type": "python",
            "request": "launch",
            "module": "uvicorn",
            "args": [
                "src.main:app",
                "--reload",
                "--port",
                "8000"
            ],
            "jinja": true,
            "justMyCode": false
        },
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": false
        },
        {
            "name": "Python: Tests",
            "type": "python",
            "request": "launch",
            "module": "pytest",
            "args": [
                "-v",
                "tests/"
            ],
            "justMyCode": false
        }
    ]
}

VS Code Usage

Running the Server:
Open the Debug panel (Ctrl+Shift+D / Cmd+Shift+D)
Select "Python: FastAPI" from the dropdown
Press F5 or click the green play button
Debugging:
Set breakpoints by clicking left of line numbers
Use the Debug toolbar to:
- Continue (F5)
- Step Over (F10)
- Step Into (F11)
- Step Out (Shift+F11)
Running Tests:
Option 1: Using Test Explorer
- Open the Testing panel (Ctrl+Shift+T / Cmd+Shift+T)
- Click Run All Tests or individual test buttons
Option 2: Using Debug Configuration
- Select "Python: Tests" from debug dropdown
- Press F5 to run with debugger
Integrated Terminal:
Open terminal: Ctrl+/ Cmd+
Your virtual environment should activate automatically
Code Navigation:
Go to Definition: F12
Find All References: Shift+F12
Quick Fix: Ctrl+. / Cmd+.

Starting the Server

Run the development server:

uvicorn src.main:app --reload --port 8000

API Documentation

Access the interactive API documentation: - Swagger UI: http://localhost:8000/docs - ReDoc: http://localhost:8000/redoc

API Endpoints

Method	Endpoint	Description
POST	/api/v1/tasks/	Create a new task
GET	/api/v1/tasks/	List all tasks
GET	/api/v1/tasks/{task_id}	Get a specific task
PATCH	/api/v1/tasks/{task_id}	Update a task
POST	/api/v1/tasks/{task_id}/assign	Assign a task to a user

Example Requests

Create a new task:

curl -X POST "http://localhost:8000/api/v1/tasks/" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Implement new feature",
       "description": "Add user authentication to the API",
       "assigned_to": "987fcdeb-51k2-12d3-a456-426614174000"
     }'

List all tasks:

curl "http://localhost:8000/api/v1/tasks/"

🧪 Testing

Run the test suite:

# Run all tests
pytest

# Run with coverage
pytest --cov=src tests/

# Run specific test file
pytest tests/test_task_service.py

📖 API Documentation

The API documentation includes:

Detailed request/response examples
Interactive try-it-out functionality
Schema validation information
Error response examples
Authentication details (if implemented)

Example Response

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "Implement new feature",
    "description": "Add user authentication to the API",
    "status": "PENDING",
    "assigned_to": "987fcdeb-51k2-12d3-a456-426614174000",
    "created_at": "2024-01-16T10:00:00.000Z",
    "updated_at": "2024-01-16T10:00:00.000Z"
}

🔧 VS Code Troubleshooting

Common VS Code issues and solutions:

Python Interpreter Not Found ``` Problem: VS Code can't find Python interpreter Solution:
Cmd/Ctrl + Shift + P
"Python: Select Interpreter"
Choose the interpreter from your venv ```
Debugger Not Working ``` Problem: Breakpoints not hitting Solution:
Check if you're running with debugger (F5)
Verify "justMyCode": false in launch.json
Try deleting .pytest_cache directory ```
Import Errors ``` Problem: "Import could not be resolved" Solution:
Verify PYTHONPATH in settings.json
Restart VS Code
Rebuild IntelliSense cache: Cmd/Ctrl + Shift + P -> "Developer: Reload Window" ```
Formatting Not Working ``` Problem: Code not formatting on save Solution:
Check if black is installed
Verify formatting settings in settings.json
Try manual format: Shift + Alt + F ```

🔍 Error Handling

The API provides detailed error responses:

{
    "detail": "Task not found",
    "type": "task_not_found",
    "status": 404
}

🛣️ Roadmap

Future improvements planned:

[ ] Database integration (PostgreSQL)
[ ] Authentication and authorization
[ ] Docker containerization
[ ] Rate limiting
[ ] Response caching
[ ] Advanced task features (deadlines, priorities)
[ ] WebSocket notifications
[ ] Task commenting system

🤝 Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

Please ensure your PR: - Includes tests - Updates documentation - Follows the existing code style - Includes a clear description of changes

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

✨ Best Practices

Clean Architecture principles
SOLID design principles
Domain-Driven Design
Type safety
Comprehensive testing
Detailed documentation
Error handling
Logging
API versioning

💡 Tips for Development

Use the interactive API documentation for testing
Check the examples in the documentation
Follow the existing code structure
Run tests before submitting changes
Keep the architecture layers separate

📚 Additional Resources

🤔 Questions?

Feel free to: 1. Open an issue 2. Start a discussion 3. Submit a pull request 4. Contact the maintainers

License

MIT License