WorkTime - AI Assistant Guidelines

Project Overview

A React + TypeScript time tracking web app using Firebase, Tailwind CSS, and Vite.

Code Philosophy

1. Clean Code

• Write self-documenting code with meaningful names
• Keep functions small and focused (single responsibility)
• Avoid deep nesting; prefer early returns
• No magic numbers/strings; use named constants
• DRY (Don't Repeat Yourself) - extract common patterns

2. Architecture

• Business logic in services (src/services/), not in components
• Feature folders for services (e.g., balance/, schedule/, scroll/)
• Components are presentational: receive props, render UI, emit events
• Custom hooks for reusable stateful logic
• Pure functions are preferred - easier to test and reason about

3. Test-Driven Development (TDD)

When doing TDD:

1. Write tests first, before implementing the real code
2. Run tests to confirm they fail
3. Implement the minimum code to make tests pass
4. Refactor if needed
5. Run tests again to confirm they still pass

General testing guidelines:

• Keep tests focused and fast
• Pure functions in services are easier to test
• Tests live in tests/ mirroring src/ structure

4. React Best Practices (These Take Precedence)

• Functional components with hooks (no class components)
• Separate container logic from presentational components
• Keep components small and focused
• Lift state up only when necessary
• Use TypeScript strictly (avoid any)
• Props over context for explicit dependencies (when practical)

Project Structure

src/
├── components/     # Reusable UI components
├── pages/          # Route-level components
├── services/       # Business logic (feature folders)
│   ├── auth/
│   ├── balance/
│   ├── scroll/
│   └── ...
└── types/          # TypeScript types

tests/
└── services/       # Mirrors src/services structure

Commands

• Dev server: npm run dev
• Run all tests: npm test
• Run specific tests: npm test -- --testPathPattern="<pattern>"
• Build: npm run build
• Lint: npm run lint
• Full check (TypeScript + lint + tests): npm run check — run this before committing

Tech Stack

• React 18 + TypeScript
• Vite (build tool)
• Tailwind CSS (styling)
• Firebase (auth + Firestore)
• Jest (testing)

Git Workflow

• Show commit message drafts before committing
• Use semantic commit messages (feat:, fix:, refactor:, etc.)
• Don't push or create PRs without explicit approval

Agent test login mode

To run the app in local dev with a hard-coded test user while still keeping real Firebase auth available:

1. Add these environment variables to .env.local:

VITE_AGENT_TEST_AUTH_ENABLED=true
VITE_AGENT_TEST_EMAIL=agent-test@example.com
VITE_AGENT_TEST_PASSWORD=agent-test-password

1. Start dev server as usual:

npm run dev

1. On the login page, use the configured credentials (or click "Fill test credentials").

When VITE_AGENT_TEST_AUTH_ENABLED is not set to true, the app uses normal Firebase auth behavior.

Security warning

Agent test login mode is only for local development and must never be enabled in production. All VITE_* environment variables are embedded in the client bundle, so the test password is not secret and must not be treated as a secure credential.

UI verification expectations

When making UI changes, always verify both:

• Desktop layout
• Mobile layout

This should be part of every agent-driven change validation.

Be explicit in validation notes:

• List every screen/route checked.
• If the change affects a shared layout/component, verify all impacted screens on desktop and mobile.
• For general UI-impacting changes, validate at least: /login, /timesheet, /stats, /settings on both desktop and mobile.
• If any screen is not verified, clearly state it as a gap.