From 38deca45623c49f4bb91e31055cce62010cfd9af Mon Sep 17 00:00:00 2001 From: Ned Halksworth Date: Wed, 27 May 2026 14:28:46 +0100 Subject: [PATCH] feat: add AGENTS.MD and CLAUDE.MD --- AGENTS.md | 220 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 220 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 440 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0d4e8e4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,220 @@ +# 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 +```bash +npm install +``` + +### Local Development Server +Starts a local development server at `http://localhost:5173`. +```bash +npm run dev +``` + +### Production Build & Bundling +Performs TypeScript diagnostic type-checks and compiles the application into the `dist/` directory. +```bash +npm run build +``` + +### Production Preview +Runs a local web server to preview the built production bundle. +```bash +npm run preview +``` + +### Code Linting +Runs ESLint over TypeScript files to identify syntax issues and code style warnings. +```bash +npm run lint +``` + +### Appwrite Cloud Database Setup +Automatically provisions the databases, tables, columns, and indexes on the configured Appwrite instance. +```bash +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 + +```mermaid +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](file:///Users/ned/Documents/GitHub/Red%20Bull%20Tracking%20System/APPWRITE_SETUP.md) – Detailed guide on database configuration, attributes, indexes, and row permissions. +- [Appwrite Admin Schema Migrations](file:///Users/ned/Documents/GitHub/Red%20Bull%20Tracking%20System/scripts/setup-appwrite.mjs) – Automated table creation and attributes loader script. +- > TODO: Put architecture decision records (ADRs) or technical whitepapers under a dedicated `/docs` directory. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0d4e8e4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,220 @@ +# 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 +```bash +npm install +``` + +### Local Development Server +Starts a local development server at `http://localhost:5173`. +```bash +npm run dev +``` + +### Production Build & Bundling +Performs TypeScript diagnostic type-checks and compiles the application into the `dist/` directory. +```bash +npm run build +``` + +### Production Preview +Runs a local web server to preview the built production bundle. +```bash +npm run preview +``` + +### Code Linting +Runs ESLint over TypeScript files to identify syntax issues and code style warnings. +```bash +npm run lint +``` + +### Appwrite Cloud Database Setup +Automatically provisions the databases, tables, columns, and indexes on the configured Appwrite instance. +```bash +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 + +```mermaid +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](file:///Users/ned/Documents/GitHub/Red%20Bull%20Tracking%20System/APPWRITE_SETUP.md) – Detailed guide on database configuration, attributes, indexes, and row permissions. +- [Appwrite Admin Schema Migrations](file:///Users/ned/Documents/GitHub/Red%20Bull%20Tracking%20System/scripts/setup-appwrite.mjs) – Automated table creation and attributes loader script. +- > TODO: Put architecture decision records (ADRs) or technical whitepapers under a dedicated `/docs` directory.