Red-Bull-Tracker/AGENTS.md

Project Overview

Red Bull Intake Tracker is a premium web-based tracking dashboard designed for tracking caffeine and beverage consumption, with a strong focus on Red Bull products. Built using React, Vite, and TypeScript, it allows users to record intake (amount, flavour, size, price, timestamp, and location), monitor daily spending and caffeine limits, view structured trends and streaks, import/export data via styled Excel or JSON formats, and engage in real-time encrypted-compatible dialogue with an AI wellness coach powered by a serverless Ollama proxy endpoint. Synchronized dynamically with Appwrite Cloud databases using secure row-level document permissions, it delivers a highly reactive, personalized, and privacy-first self-tracking experience.

Repository Structure

• api/ – Contains serverless backend handlers, including the API gateway proxy for Ollama chat endpoints.
• dist/ – Contains static HTML, JavaScript, and CSS bundle files output by the production build process.
• node_modules/ – Stores third-party library dependencies and packages managed by npm.
• scripts/ – Houses automation scripts, including database schema configuration tools for Appwrite.
• src/ – Contains client-side React source code, components, utility models, and stylesheets.
  • src/components/ – Reusable UI panel elements, forms, and splash screen wrappers.
  • src/data/ – Static configurations, including theme lists and built-in flavours mapping.
  • src/lib/ – Business logic engines for calculations, file parsers, and Appwrite client connections.

Build & Development Commands

Use the following shell-ready commands to install dependencies, run the application, lint the code, and manage the cloud database.

Dependency Installation

npm install

Local Development Server

Starts a local development server at http://localhost:5173.

npm run dev

Production Build & Bundling

Performs TypeScript diagnostic type-checks and compiles the application into the dist/ directory.

npm run build

Production Preview

Runs a local web server to preview the built production bundle.

npm run preview

Code Linting

Runs ESLint over TypeScript files to identify syntax issues and code style warnings.

npm run lint

Appwrite Cloud Database Setup

Automatically provisions the databases, tables, columns, and indexes on the configured Appwrite instance.

npm run setup:appwrite

Automated Testing

TODO: Add automated test suite command (e.g., npm run test using Vitest or Jest).

Application Deployment

TODO: Add production deployment pipeline command (e.g., Vercel, Netlify, or Docker deploy).

Code Style & Conventions

• Language: TypeScript is strictly required for all UI components and logic scripts; JavaScript is limited to serverless handlers and build scripting.
• Strict Checks: TypeScript's strict compiler option is enabled; avoid using any and ensure all parameters and return values are explicitly typed.
• Formatting: Code should be formatted with 2-space indentation, trailing commas where supported, and double quotes for JSX/TSX properties.
• Linting: Rules are governed by ESLint (eslint.config.js), extending the standard TypeScript and React Hooks rulesets.
• Naming Conventions:
  • React components and files use PascalCase (e.g., CoachPanel.tsx).
  • Business logic, utilities, and helper hooks use camelCase (e.g., appwriteEntries.ts, useCoachSession.ts).
  • Constants and static metadata arrays use UPPER_SNAKE_CASE (e.g., BUILT_IN_FLAVOURS).
• Imports: Prefer explicit ES module imports (import { ... } from "..."). Avoid wildcards.
• Commit Messages:

  • TODO: Define commit message guidelines and templates (e.g., Conventional Commits).

Architecture Notes

Flow Architecture Diagram

graph TD
    subgraph Frontend [Vite React Client]
        App[App.tsx - Core State & Shell]
        Components[Onboarding, CoachPanel, Limits, etc.]
        LibMetrics[metrics.ts & userLimits.ts]
        LibIO[excel.ts & storage.ts]
        LibTheme[themeTokens.ts & themes.ts]
        HookCoach[useCoachSession.ts]
    end

    subgraph BackendAPI [API & Proxies]
        ViteProxy[Vite Dev Server Middleware]
        VercelHandler[api/ollama-chat.js Serverless Function]
    end

    subgraph External [External Services]
        AppwriteCloud[Appwrite Cloud / TablesDB]
        OllamaAPI[Ollama Cloud API]
    end

    App --> Components
    App --> LibMetrics
    App --> LibIO
    App --> LibTheme
    App --> HookCoach

    HookCoach -- "/api/ollama-chat (Local)" --> ViteProxy
    HookCoach -- "/api/ollama-chat (Prod)" --> VercelHandler
    
    ViteProxy -- "Headers Auth" --> OllamaAPI
    VercelHandler -- "Headers Auth" --> OllamaAPI

    App --> AppwriteCloud

Component Roles & Data Flow

1. State Orchestration (src/App.tsx): Acts as the monolithic hub of the frontend. It manages user authentication states, currently selected views, active database operations, modals, onboarding triggers, and theme settings.

2. Metrics & Limits (src/lib/metrics.ts, src/lib/userLimits.ts): Process raw intakes to extract total cans, spendings, caffeine absorption, hydration estimates, streaks, and coordinate warnings when user limits are breached or bedtime approaches.

3. External Data Codecs (src/lib/excel.ts, src/lib/storage.ts): Implement styled spreadsheet formatting with exceljs, data sanity validation, duplicate-aware import preview engines, and local JSON backup/restore modules.

4. Dynamic Styling (src/lib/themeTokens.ts, src/data/themes.ts): Computes CSS tokens dynamically from a selection of Vocaloid or beverage-themed configurations, writing variables into the document root for real-time visual styling modifications.

5. Cloud Synced State (src/lib/appwrite.ts, src/lib/appwriteEntries.ts, src/lib/coachChats.ts): Establishes client tunnels to Appwrite's serverless TablesDB backend, running row-secured CRUD actions bound strictly to the current userId.

6. AI Coach Chatbot (src/lib/useCoachSession.ts, api/ollama-chat.js): A state-machine custom hook that pipelines user questions, injects historical intake aggregates, and streams responses from DeepSeek through server-side Ollama proxy tunnels.

Testing Strategy

The repository does not currently feature automated test files. Testing is executed manually.

Unit & Integration Testing

• TODO: Configure unit and integration tests (e.g., Vitest + React Testing Library) to validate metrics computations, limits checks, and file importing codecs.

End-to-End (E2E) Testing

• TODO: Introduce E2E test suites (e.g., Playwright or Cypress) to cover authentication paths, entry additions, theme switches, and chatbot conversation loops.

Continuous Integration (CI)

• TODO: Establish a GitHub Actions workflow pipeline to run linters, type checks, and tests on every branch commit or pull request.

Security & Compliance

• Authentication: Delegated entirely to Appwrite's built-in OAuth/Email-password protocols. No user passwords or direct login credentials are saved inside the application state.
• Client Security: Client-side application calls only the Appwrite browser SDK. No administrative or server-level API keys are ever shipped or exposed to the client.
• Database Row Security: All Appwrite tables have Row Security enabled. Users are granted create permissions on the table level, but read, update, and delete actions require explicit document permissions matching the user's specific ID (user:{userId}).
• LLM API Security: To avoid key exposure, the client connects to the proxy path /api/ollama-chat. The secret OLLAMA_API_KEY is maintained exclusively in secure server-side environment variables.
• Dependency Auditing:

  • TODO: Add automated dependency checking (e.g., npm audit or Dependabot) in the CI pipeline.

• Software Licensing:

  • TODO: Add a standard LICENSE file (e.g., MIT, Apache-2.0) to explicitly detail terms of reuse.

Agent Guardrails

• Environment File Preservation: Never edit, modify, or commit variables directly inside .env.local or .env templates unless explicitly instructed by the user.
• Credential Safety: Never add, write, or hardcode API keys, access secrets, project keys, or personal tokens into the codebase or configuration files.
• Safe Directory Boundaries: Do not add, write, or alter files inside administrative, system, or auto-generated directories like .git, .gemini, dist, or node_modules.
• Monolithic State Warnings: src/App.tsx contains the core layout and view engine. Exercise extreme care when making adjustments to prevent breaking the view transitions, auth hooks, or modals.
• Database Alignment Rules: Always verify that any changes to DB record structures or types are mirrored across src/types.ts, Appwrite modules (src/lib/appwriteEntries.ts, src/lib/coachChats.ts), and the migration runner scripts/setup-appwrite.mjs.

Extensibility Hooks

• Flavour Extensions: New built-in Red Bull flavours, accent colors, and sugar-free rules can be easily appended to the BUILT_IN_FLAVOURS array in src/data/flavours.ts.
• UI Custom Themes: Additional visual themes, including Vocaloid, seasonal, or custom branding, can be integrated by adding definitions to the APP_THEMES array in src/data/themes.ts.
• Proxy Endpoint Rerouting: The Ollama upstream proxy route in vite.config.ts and api/ollama-chat.js can be adjusted to point to alternative LLM hosts or local server instances.
• Configurable Environment Parameters:
  • VITE_APPWRITE_ENDPOINT – Base URL for the Appwrite API server.
  • VITE_APPWRITE_PROJECT_ID – The Appwrite project instance identifier.
  • VITE_APPWRITE_DATABASE_ID – TablesDB target database identifier.
  • VITE_APPWRITE_COLLECTION_ID – Table ID containing intake documents.
  • VITE_APPWRITE_CHAT_COLLECTION_ID – Table ID storing coach chatbot threads.
  • OLLAMA_API_KEY – Administrative bearer authorization token for Ollama endpoints.
  • OLLAMA_MODEL – Upstream model identifier (default: deepseek-v4-pro:cloud).

Further Reading

• Appwrite Platform Documentation – Detailed guide on database configuration, attributes, indexes, and row permissions.
• Appwrite Admin Schema Migrations – Automated table creation and attributes loader script.

• TODO: Put architecture decision records (ADRs) or technical whitepapers under a dedicated /docs directory.