A production-ready developer productivity API for tracking daily coding sessions, analyzing patterns, and getting automated weekly summaries.

DevLog helps developers track their daily work by logging coding sessions with details about what they worked on, how long it took, what they learned, and what blocked them. The system automatically generates weekly summaries showing your most productive projects and common blockers.

This is a real backend system demonstrating production-ready FastAPI development with authentication, background jobs, scheduled tasks, proper database design, and CI/CD with automated testing.

• Session Management (Full CRUD)

  • Create, read, update (PUT & PATCH), and delete coding sessions
  • Session status tracking (active, DRAFT, completed)
  • Filter sessions by project name and duration range
  • Cursor-based pagination for efficient data retrieval
  • Draft sessions endpoint (GET /sessions/drafts)

• Authentication & Authorization

  • User registration and login with JWT tokens
  • Protected endpoints — users can only access their own data
  • Secure password hashing with bcrypt

• Weekly Summaries (Background Jobs)

  • Automated weekly summary generation via Celery Beat
  • Runs every Sunday at midnight UTC
  • Calculates: total sessions, total minutes, top project, most common blocker
  • Manual trigger endpoint (POST /summary/trigger)
  • Persisted to database for historical tracking

• GitHub Webhook Integration

  • Auto-creates sessions from GitHub push events
  • Matches users by commit author or pusher email
  • Extracts repo name, commit messages, and files changed
  • Estimates session duration (15 min per commit)

• Testing & CI/CD

  • 76% test coverage with pytest
  • 19 automated tests (6 auth, 10 sessions, 3 summary logic)
  • GitHub Actions pipeline running on every push
  • PostgreSQL + Redis integration testing in CI
  • Automated test runs in ~45 seconds

• Docker & Infrastructure

  • Full Docker Compose setup (5 services)
  • Async Alembic migrations (run inside Docker)
  • Hot-reload development with volume mounts

• RESTful API

  • Intuitive endpoint design
  • Pydantic v2 validation for all inputs
  • Automatic API documentation with Swagger UI

• Redis caching for weekly summaries (Phase 6)
• Request logging and rate limiting (Phase 7)
• Full-text search (Phase 8)
• Semantic search with pgvector (Phase 9)
• MCP server integration (Phase 10)

DevLog has a comprehensive test suite covering authentication, session management, and summary generation logic.

• Overall Coverage: 76%
• Total Tests: 19 (all passing)
  • Authentication tests: 6
  • Session management tests: 10
  • Summary logic tests: 3

# Install dependencies
uv sync

# Run all tests with coverage
uv run pytest --cov=app --cov-report=term-missing

# Run specific test file
uv run pytest app/tests/test_auth.py -v

# Run tests in verbose mode
uv run pytest -v

The project uses GitHub Actions for automated testing on every push to main or develop branches:

• Environment: Python 3.12, PostgreSQL 16, Redis 7
• Services: Automated PostgreSQL and Redis setup
• Speed: Complete test run in ~45 seconds
• Coverage: Tracks and reports test coverage

View the workflow at .github/workflows/test.yml

┌─────────────┐      ┌──────────────┐      ┌──────────────┐
│   Client    │─────▶│  FastAPI API │─────▶│  PostgreSQL  │
│  (HTTP/JSON)│      │   (port 8000)│      │  (port 5432) │
└─────────────┘      └──────────────┘      └──────────────┘
                            │
                            │
                     ┌──────▼──────┐
                     │    Redis    │
                     │ (port 6379) │
                     └──────┬──────┘
                            │
              ┌─────────────┴─────────────┐
              │                           │
       ┌──────▼──────┐           ┌───────▼──────┐
       │Celery Worker│           │ Celery Beat  │
       │(Tasks exec) │           │  (Scheduler) │
       └─────────────┘           └──────────────┘

• Docker and Docker Compose installed
• Git (to clone the repository)

1. Clone the repository

   git clone <your-repo-url>
   cd Future

2. Start all services

   docker-compose up -d

   This starts:

   • PostgreSQL database
   • Redis (message broker)
   • FastAPI API server
   • Celery worker (background tasks)
   • Celery beat (task scheduler)

3. Run database migrations

   docker-compose exec api uv run alembic upgrade head

4. Access the API

   • API: http://localhost:8000
   • Interactive docs: http://localhost:8000/docs
   • Alternative docs: http://localhost:8000/redoc

Check that all containers are running:

docker-compose ps

You should see 5 services as "Up".

Run the test suite to verify everything works:

docker-compose exec api uv run pytest --cov=app

You should see 19 tests pass with 76% coverage.

View logs:

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f api
docker-compose logs -f celery_worker

curl -X POST http://localhost:8000/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "securepass123"
  }'

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=dev@example.com&password=securepass123"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

curl -X POST http://localhost:8000/sessions/ \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "DevLog API",
    "worked_on": "Implemented weekly summary generation",
    "duration": "120",
    "what_learned": "Celery Beat scheduling and task design",
    "blockers": "Docker networking configuration"
  }'

# All sessions (paginated)
curl http://localhost:8000/sessions/ \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

# Filter by project
curl "http://localhost:8000/sessions/?project=DevLog" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

# Filter by duration
curl "http://localhost:8000/sessions/?duration_min=60&duration_max=180" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

curl http://localhost:8000/summary/ \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

Response:

[
  {
    "id": "uuid-here",
    "user_id": "uuid-here",
    "week_start": "2026-04-07T00:00:00Z",
    "total_sessions": 5,
    "total_minutes": 420,
    "top_project": "DevLog API",
    "most_common_blocker": "Docker networking",
    "created_at": "2026-04-14T00:00:00Z"
  }
]

• POST /auth/register - Register a new user
• POST /auth/login - Login and get JWT token
• GET /auth/me - Get current user info

• POST /sessions/ - Create a new session
• GET /sessions/ - List sessions (with filters & pagination)
• GET /sessions/drafts - Get all draft sessions
• GET /sessions/{id} - Get a specific session
• PUT /sessions/{id} - Full update a session
• PATCH /sessions/{id} - Partial update a session
• DELETE /sessions/{id} - Delete a session

• GET /summary/ - Get your weekly summaries (latest first)
• GET /summary/latest - Get most recent weekly summary
• POST /summary/trigger - Manually trigger summary generation

• POST /webhooks/github - GitHub push event webhook (auto-creates sessions)

1. Install dependencies

   uv sync

2. Start PostgreSQL and Redis

   docker-compose up -d postgres redis

3. Set environment variables (create .env)

   DATABASE_URL=postgresql+asyncpg://devlog:devlog123@localhost:5432/devlog
   postgres_url=postgresql+asyncpg://devlog:devlog123@localhost:5432/devlog
   REDIS_URL=redis://localhost:6379/0
   SECRET_KEY=your-secret-key-change-in-production

4. Run migrations

   uv run alembic upgrade head

5. Start the API

   uv run uvicorn main:app --reload

6. Start Celery worker (in another terminal)

   uv run celery -A app.celery_app worker --pool=solo

7. Start Celery beat (in another terminal)

   uv run celery -A app.celery_app beat

Create a migration (run inside Docker to avoid Windows networking issues):

docker exec -it devlog_celery_worker uv run alembic revision --autogenerate -m "description"

Apply migrations:

docker exec -it devlog_celery_worker uv run alembic upgrade head

Rollback one migration:

docker exec -it devlog_celery_worker uv run alembic downgrade -1

Access PostgreSQL:

docker-compose exec postgres psql -U devlog -d devlog

Run SQL query:

docker-compose exec postgres psql -U devlog -d devlog -c "SELECT * FROM sessions LIMIT 5;"

# Stop all containers
docker-compose down

# Stop and remove volumes (DELETES ALL DATA)
docker-compose down -v

• id (UUID, primary key)
• email (string, unique, indexed)
• password_hash (string)
• created_at (timestamp with timezone)

• id (UUID, primary key)
• user_id (UUID, foreign key → users)
• project (string)
• worked_on (string)
• duration (string)
• what_learned (string)
• blockers (string)
• status (string, default: "active" — e.g. active, DRAFT, completed)
• date (timestamp with timezone, indexed)
• updated_at (timestamp with timezone)

• id (UUID, primary key)
• user_id (UUID, foreign key → users)
• week_start (timestamp with timezone)
• total_sessions (integer)
• total_minutes (integer)
• top_project (string, nullable)
• most_common_blocker (string, nullable)
• created_at (timestamp with timezone)

DevLog supports full session CRUD (including PUT/PATCH), draft sessions, user authentication, filtering/pagination, automated weekly summaries via Celery Beat, and GitHub webhook integration for auto-tracking push activity. Fully Dockerized with async Alembic migrations. Now includes comprehensive test suite (76% coverage) and CI/CD pipeline with GitHub Actions.

1. Phase 1-2: Core session CRUD + User authentication (JWT)
2. Phase 3: Filtering, pagination, and draft sessions
3. Phase 4: Automated weekly summaries (Celery Beat) + GitHub webhooks
4. Phase 5: Comprehensive testing + CI/CD pipeline (GitHub Actions)

1. Phase 6: Caching — Redis cache for weekly summaries with TTL
2. Phase 7: Observability — Request tracing, structured logging, rate limiting
3. Phase 8: Search — PostgreSQL full-text search across sessions
4. Phase 9: AI Layer — Semantic search with pgvector and LLM summarization
5. Phase 10: MCP Integration — Expose as MCP server for Claude/Copilot
6. Phase 11: Production Deployment — Deploy to Railway/Fly.io with production configs

docker-compose logs api
docker-compose logs celery_worker

• Verify postgres container is healthy: docker-compose ps
• Check environment variables match in all services

# Find what's using port 8000
lsof -i :8000  # Mac/Linux
netstat -ano | findstr :8000  # Windows

# Change port in docker-compose.yml if needed
ports:
  - "8001:8000"  # Use host port 8001 instead

# Check worker status
docker-compose exec celery_worker celery -A app.celery_app inspect active

# Check beat schedule
docker-compose logs celery_beat

This project is for educational purposes. Feel free to use it as a learning resource or template for your own projects.

Built as a comprehensive backend learning project demonstrating FastAPI, Celery, Docker, PostgreSQL, and modern Python development practices.