TaskFlow — AI-Assisted Productivity & Planning

TaskFlow is a modern, cloud-ready task manager with an AI assistant that helps you prioritize tasks, generate a daily plan, and keep momentum. Built as a real-world, production-style project to showcase backend + AI + cloud skills.

Quick Start (Docker)

docker compose up -d --build
docker compose exec api alembic upgrade head

Then open:

• Backend API docs: http://localhost:8000/docs
• Frontend: http://localhost:5173

Features

• Task Management: Projects, tasks, due dates, statuses, tags
• AI Assistant: OpenAI-powered prioritization with rationale and daily plan generation
• Search & Filters: By project, status, tags, due range
• Auth: Register/login with JWT tokens
• Fast APIs: FastAPI + Pydantic + OpenAPI docs
• Scalable DB: PostgreSQL + SQLAlchemy + Alembic migrations
• Caching & Rate Limiting: Redis-backed with per-user limits
• DevOps Ready: Docker, CI/CD (GitHub Actions), Prometheus metrics, AWS ECS deployment

Architecture

┌─────────────────────────────┐
│  React (Vite + Tailwind)    │
└──────────────┬──────────────┘
               │ HTTPS (JWT)
┌──────────────▼──────────────┐
│  FastAPI Backend            │
│  - /auth, /tasks, /projects │
│  - /ai/prioritize, /metrics │
└──────────────┬──────────────┘
               │
     ┌─────────┼──────────┐
     │         │          │
┌────▼─┐  ┌───▼──┐  ┌────▼────────┐
│Redis │  │  PG  │  │ OpenAI API   │
│cache │  │  DB  │  │ (external)   │
└──────┘  └──────┘  └─────────────┘

Tech Stack

• Frontend: React (Vite), Tailwind, React Query
• Backend: Python, FastAPI, Pydantic, SQLAlchemy, Alembic, JWT
• Databases: PostgreSQL, Redis
• AI: OpenAI GPT-4, rule-based fallback
• DevOps: Docker, Docker Compose, GitHub Actions, AWS ECS + RDS + ECR
• Testing: pytest, httpx, React Testing Library

Repository Structure

taskflow/
├── backend/
│   ├── app/
│   │   ├── main.py              (FastAPI app and routes)
│   │   ├── config.py            (settings via pydantic)
│   │   ├── models.py            (SQLAlchemy models)
│   │   ├── schemas.py           (Pydantic DTOs)
│   │   ├── deps.py              (dependencies: db, auth)
│   │   ├── routers/
│   │   │   ├── auth.py
│   │   │   ├── tasks.py
│   │   │   ├── projects.py
│   │   │   └── ai.py
│   │   ├── services/
│   │   │   ├── ai.py            (rule-based + LLM adapter)
│   │   │   └── tasks.py         (business logic)
│   │   └── utils/               (hashing, rate limit, logging)
│   ├── alembic/                 (DB migrations)
│   ├── tests/                   (pytest)
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── hooks/
│   │   ├── App.tsx
│   │   └── main.tsx
│   ├── vite.config.ts
│   ├── Dockerfile
│   └── package.json
├── docker-compose.yml
├── .env.example
└── README.md

Environment Variables (.env)

Backend

DATABASE_URL=postgresql+psycopg://taskflow:taskflow@db:5432/taskflow
REDIS_URL=redis://cache:6379/0
JWT_SECRET=your_super_secret_key_change_this
OPENAI_API_KEY=sk-your_openai_key_here
AI_PROVIDER=openai
CORS_ORIGINS=http://localhost:5173
LOG_LEVEL=INFO

Frontend

VITE_API_BASE=http://localhost:8000

Running Locally

With Docker (recommended)

# Build and start all services
docker compose up -d --build

# Run migrations
docker compose exec api alembic upgrade head

# Check logs
docker compose logs -f api

# Stop
docker compose down

Without Docker

Backend:

cd backend
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt
alembic upgrade head
uvicorn app.main:app --reload

Frontend:

cd frontend
npm install
npm run dev

API Endpoints

Auth

• POST /auth/register — email, password → access_token, refresh_token
• POST /auth/login — email, password → access_token, refresh_token
• POST /auth/refresh — refresh_token → access_token

Tasks

• GET /tasks?status=&project_id=&due_from=&due_to=&skip=0&limit=20 — list tasks
• POST /tasks — create task
• GET /tasks/{id} — get task
• PATCH /tasks/{id} — update task
• DELETE /tasks/{id} — delete task

Projects

• GET /projects — list projects
• POST /projects — create project
• PATCH /projects/{id} — update project
• DELETE /projects/{id} — delete project

AI

• POST /ai/prioritize — prioritize a list of tasks with OpenAI

Example request:

{
  "tasks": [
    {
      "title": "Finish OS HW2",
      "due_at": "2025-02-01T17:00:00Z",
      "estimated_minutes": 120,
      "importance": 5
    },
    {
      "title": "Apply to 5 SWE internships",
      "due_at": null,
      "estimated_minutes": 90,
      "importance": 4
    }
  ]
}

Example response:

{
  "results": [
    {
      "title": "Finish OS HW2",
      "score": 0.91,
      "rationale": "Imminent deadline; high importance; manageable effort."
    },
    {
      "title": "Apply to 5 SWE internships",
      "score": 0.78,
      "rationale": "Career critical; no hard deadline; schedule today if time remains."
    }
  ],
  "plan": [
    "14:00-16:00 Finish OS HW2",
    "16:15-17:45 Apply to internships",
    "18:00-19:00 Break and review progress"
  ]
}

Health & Observability

• GET /healthz — health check
• GET /readyz — readiness check
• GET /metrics — Prometheus metrics

Testing

Backend

docker compose exec api pytest -v

Frontend

cd frontend
npm test

Deployment

AWS ECS + RDS + ECR

1. Build and push images to ECR:

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-east-1.amazonaws.com
docker build -t taskflow-api backend/
docker tag taskflow-api:latest <account-id>.dkr.ecr.us-east-1.amazonaws.com/taskflow-api:latest
docker push <account-id>.dkr.ecr.us-east-1.amazonaws.com/taskflow-api:latest

2. Create ECS task definition, service, load balancer (see Terraform in /infra or AWS Console)

3. Create RDS Postgres and ElastiCache Redis in same VPC

4. Set environment variables in ECS task definition

Simpler Alternative: Render or Railway

• Push repo to GitHub
• Connect to Render/Railway
• Add Postgres and Redis add-ons
• Set environment variables
• Deploy

CI/CD

GitHub Actions workflow (.github/workflows/ci.yml):

• Run pytest and frontend tests on every PR
• Build Docker images
• Push to ECR on main branch
• Deploy to ECS on tag

Performance & Cost

• Cold start: ~2s (FastAPI startup)
• Median latency (GET /tasks): ~45ms (local, with cache)
• Monthly cost (AWS ECS + RDS + ECR): ~$50–100 depending on instance sizing