tatlock-ui/AGENTS.md

LLM Agent Instructions

This document contains instructions and documentation references for AI assistants working with this codebase.

📖 Important: Before working on this project, read PHILOSOPHY.md to understand the system vision, architectural patterns, and design goals. All development should work towards realizing those patterns.

AGENTS.md

Start every session by reading this file. This file outlines the operational protocols, coding standards, and architectural decisions for this Flutter 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?

🌐 Internal Service Access

• git.schweitz.net: Access via http://localhost:3002 (direct Gitea) to bypass Authentik SSO
  • Example: curl http://localhost:3002/jpmschweitzer/library-desk/raw/branch/main/README.md
  • Public repos are readable without authentication
  • Related repos: , core-api, tatlock, library-desk, scheduler, portainer-core

🐳 Deployment & Infrastructure

⚠️ IMPORTANT: Service Port Reference

Service	LAN Port	External URL	Notes
Core API	8083	api.schweitz.net	FastAPI backend for this UI
Tatlock API	8000	tatlock.schweitz.net	Legacy Python API (Ollama proxy)
Tatlock UI	9999	home.schweitz.net	This Flutter app

• Full stack documentation: Available in the portainer-core repo
  • Access: curl http://192.168.86.149:3002/jpmschweitzer/portainer-core/raw/branch/main/CONTAINERS.md
  • Contains: All service ports, URLs, Redis DB allocations, external domains
• Health checks:
  • Core API: curl http://192.168.86.149:8083/health
  • Tatlock API: curl http://192.168.86.149:8000/health

🛡️ Git Discipline

• 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.
• Version Tagging: Every version increment (major.minor.patch, not build count) must have a corresponding git tag.
  • Format: v{major}.{minor}.{patch} (e.g., v0.3.0)
  • Tag after updating pubspec.yaml version and CHANGELOG
  • Push tags with git push --tags

🚀 Release Procedure

This project uses version-tag-based CI/CD. Releases trigger automated Docker builds and deployments.

Release Steps:

1. Update version in pubspec.yaml (bump major.minor.patch, not build number)
2. Update CHANGELOG.md with changes under ## [x.x.x] - YYYY-MM-DD
3. Commit changes: git commit -m "chore: release vX.X.X"
4. Create git tag: git tag vX.X.X
5. Push with tags: git push origin master --tags

CI/CD auto-triggers when a tag starting with v is pushed.

What happens on release:

• Gitea CI builds Flutter web app in Docker
• Image pushed to git.schweitz.internal/jpmschweitzer/tatlock-ui:latest and :vX.X.X
• Watchtower detects new image and auto-updates running container
• App available at http://tower:8092 (and eventually home.schweitz.net)

Rollback:

• In Portainer, update image tag to previous version (e.g., :v0.2.0)
• Or: docker pull git.schweitz.internal/jpmschweitzer/tatlock-ui:v0.2.0

🧪 Testing Requirements

• Always add tests for new code before committing. No exceptions.
• Tests should cover the happy path and key edge cases.
• Run flutter test before committing to ensure all tests pass.
• For widgets: use widget tests. For business logic: use unit tests.
• Code coverage should not decrease with new commits.

📝 Changelog Maintenance

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

🎨 UI Patterns (MUST READ BEFORE CHANGES)

• Before modifying the widget tree, read docs/UI_LAYOUT.md to understand established patterns.
• Investigate existing implementations in the codebase before creating new components.
• DO NOT reinvent wheels - check if shared components already exist in lib/shared/components/.
• Look at similar features for reference patterns (e.g., how other list views, forms, or CRUD screens are built).
• Deviating from established patterns creates inconsistency and technical debt.