ChatKcal Documentation

Mission

ChatKcal is an AI-first calorie tracker designed to simplify nutrition logging by leveraging the power of Large Language Models (LLMs). This documentation serves as the central source of truth for our architecture, development standards, and project roadmap.

---

🏗️ Architecture

Deep dives into the system design, including our offline-first approach and testing philosophy.

• Data Model: Single Table Design and aggregation logic.
• Frontend & Offline: PWA and TanStack Query persistence.
• Testing Strategy: Our "Testing Trophy" approach and CI/CD gates.
• Auth & Security: Cognito integration and social sign-in.

---

📝 Development Notes

Guides, patterns, and best practices for building and maintaining ChatKcal.

• Setup & Installation: Get the project running locally.
• Best Practices:
  • ADR 006: Testing Strategy
  • Component Granularity
  • Form Handling with React Query
  • TanStack Query Persistence
• Patterns:
  • ADR 005: Frontend Service Pattern
  • Project Planning Framework
• Learnings:
  • Architecture Decision Framework
  • Refactoring Guide

---

📈 Project Management

Tracking our progress from foundation to friction-zero UX.

• Master Plan & Roadmap: The high-level goals.
• Incident Reports: Post-mortems and learnings (e.g., Settings Race Condition).
• Recent Logs:
  • Targets Persistence
  • Layered Testing Strategy
  • Offline Capability

---

🚀 Quick Start (Development)

To serve this documentation locally:

task docs

To start the frontend development server:

task dev

To build the backend:

sam build