webber/AGENTS.md

AGENTS.md

Start every session by reading this file. This file outlines the operational protocols, coding standards, and architectural decisions for this FastAPI project.

1. Agent Operational Protocols

🧠 Work Patterns (Plan-Act-Reflect)

• Plan: Before writing code, briefly outline your plan. Identify which files you will touch and what the side effects might be.
• Act: Execute the changes in small, atomic steps.
• Reflect: After coding, verify your work. Did you break existing tests? Did you add new tests?

🛡️ Git Discipline

• ALWAYS add the relevant tests for the added code Make sure to keep the test coverage up as we go, and run tests before commiting.
• NEVER commit to main or master directly. Always create a feature branch: feature/your-feature-name or fix/issue-description.
• Commit Messages: Use the Conventional Commits format.
  • feat: add user login endpoint
  • fix: resolve database connection timeout
  • refactor: split monolith dependency file
• Atomic Commits: Keep commits small. One logical change = one commit.

📝 Changelog Maintenance

• Update CHANGELOG.md with every user-facing change.
• Format: ## [Unreleased] - YYYY-MM-DD followed by ### Added, ### Changed, or ### Fixed.

🚀 Release Flow

When changes are ready for deployment:

1. **Ask user if deploy cycle is desired **

2. Update version in pyproject.toml:

   • Bug fixes: bump patch version (1.8.3 → 1.8.4)
   • New features: bump minor version (1.8.4 → 1.9.0)

3. Update CHANGELOG.md:

   • Move items from [Unreleased] to new version section
   • Add release date: ## [1.8.4] - 2025-12-16

4. Commit and tag:

   git add -A
   git commit -m "fix: description of changes"
   git tag v1.8.4
   git push origin main --tags
   

5. CI/CD triggers automatically:

   • Gitea CI builds Docker image on new version tag (starts with "v")
   • Watchtower pulls and deploys to production

---

🧪 Local Development Setup

• Always test locally first before committing and deploying. The build-deploy loop is slow.
• Only deploy when a phase or feature is complete and tested locally
• Environment: Copy .env.example to .env and configure for your local setup

⚠️ CRITICAL: Starting the Local Server

ALWAYS use ./wakeup.sh to start the local server. NEVER use raw uvicorn commands.

./wakeup.sh

The wakeup script provides:

• Port conflict detection - Warns if port 8086 is already in use
• Virtual environment activation - Ensures correct Python environment
• Centralized logging - All logs written to logs/server.log for easy tailing
• Auto-reload - Code changes picked up automatically (except requirements.txt changes)
• Consistent configuration - Same startup every time

To monitor logs in another terminal:

tail -f logs/server.log

To stop the server: Press Ctrl+C

To kill a stuck server:

pkill -f "uvicorn src.main:app"
# or
kill $(lsof -t -i:8086)

Testing

Test REST endpoints against http://localhost:8086:

curl http://localhost:8086/health
curl http://localhost:8086/
curl http://localhost:8086/docs   # Swagger UI

Running tests: Always use the venv explicitly to avoid environment mismatches:

.venv/bin/python -m pytest tests/           # All tests
.venv/bin/python -m pytest tests/ -v        # Verbose output
.venv/bin/python -m pytest tests/ --cov     # With coverage

---

2. FastAPI Architecture & Best Practices

Reference: FastAPI Best Practices

📂 Project Structure (Directory-based, NOT File-type based)

Do not group files by type (e.g., one huge routers folder). Group by domain/module inside a src/ directory.

Correct Structure:

to be determined