Skip to main content

Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
Engineering Standards and Style Guide

To maintain a high-velocity, high-quality codebase, all contributors to GrantMaster must follow these standards.
Canonical reference: CLAUDE.md at the project root is the single source of truth for conventions. This document summarizes the key points for onboarding.

​
Tech Stack (Current)

  • Frontend: React 19, TypeScript, Vite 6.2
  • Styling: Tailwind CSS 4, shadcn/ui (Radix UI primitives)
  • State/Data: React Query (@tanstack/react-query), React Context, tRPC
  • Forms: react-hook-form + Zod validation via useZodForm
  • Backend: Firebase (Auth, Firestore, Storage, Functions)
  • AI: Google Gemini via Genkit
  • Testing: Vitest (unit), Playwright (E2E)

​
💻 Clean Code Principles

  • Self-Documenting Code: Variable and function names should explain why they exist and what they do.
    • Bad: c(g)
    • Good: calculateGrantRemainingBudget(grantId)
  • Small Functions: Functions should do one thing. If a function is longer than 30 lines, consider breaking it down.
  • Early Returns: Avoid deeply nested if/else blocks. Return early wherever possible.

​
TypeScript & Types

  • No any: The use of any is strictly prohibited. Use unknown or a proper Interface/Type.
  • Interfaces vs Types:
    • Use Interfaces for public APIs and data models (they are extendable).
    • Use Types for unions, aliases, and complex conditional mappings.
  • Discriminated Unions: Use these for managing complex states (e.g., type Status = 'loading' | 'success' | 'error').

​
⚛️ React Best Practices

  • Functional Components: Class components are deprecated. Always use Functional Components with Hooks.
  • Prop Destructuring: Always destructure props in the function signature.
  • Key usage: Never use index as a key for list rendering if the list can be reordered or filtered. Use a unique ID.

​
📁 File Structure & Naming

  • Components: PascalCase (ProjectCard.tsx)
  • Hooks: camelCase with use prefix (useProjects.ts)
  • Services: camelCase (projectService.ts)
  • Types: PascalCase (Project, Employee)
  • Feature-First Organization: Group code by feature, not by type.
    • Good: src/features/billing/components, src/features/billing/hooks.
    • Avoid: src/components/billing, src/hooks/billing.

​
🧪 Testing

  • Test Behavior, Not implementation: Your tests should check that the user can do X, not that function Y was called with Z.
  • Coverage: Target 80% coverage for core business logic (Services). 100% for utility functions.

​
🔄 Commit Messages

We use Conventional Commits:
  • feat:: A new feature.
  • fix:: A bug fix.
  • docs:: Documentation changes.
  • style:: Changes that do not affect the meaning of the code (white-space, formatting).
  • refactor:: A code change that neither fixes a bug nor adds a feature.
  • test:: Adding missing tests or correcting existing tests.
  • chore:: Changes to the build process or auxiliary tools.

​
📐 UI Conventions (Mandatory)

These rules ensure visual consistency. See CLAUDE.md for the full reference.

​
Page Structure

  • Always wrap page content in <PageLayout> (@/components/ui/PageLayout)
  • Always use <PageHeader> for page titles — never manual <h1>
  • Tabs: Use <PageTabs> — render content externally, not via tab content prop
  • Organization context: useTenant() from @/contexts/TenantContext — not useOrganization
  • Secondary navigation: Use <SecondarySidebar> from @/components/ui/SecondarySidebar

​
Colors

  • Neutral palette: slate-* only — never gray-*
  • Primary actions: primary-* tokens — never hardcode blue-*
  • Success: emerald-* — never green-*
  • Error: rose-* — never red-*
  • Warning: amber-*

​
Components

  • Buttons: Always use <Button> from @/components/ui/button with isLoading / loadingText props
  • Status indicators: Use <StatusBadge> from @/components/ui/StatusBadge with mapDomainStatus()
  • Non-status labels: Use <Badge> from @/components/ui/badge
  • Cards: Use shadcn Card components or CardVariants / StatCard — never inline card styling
  • Tooltips: Use custom Tooltip from @/components/ui/Tooltip with content and side props
  • Icons: lucide-react only

​
Forms

  • Always use useZodForm from @/hooks/useZodForm for form handling (provides schema validation, toast notifications, error handling, handleSubmit/isSubmitting/isDirty)
  • Do NOT use useValidatedForm (deprecated)
  • Use <Input>, <Textarea>, <Select> from @/components/ui/ — never raw HTML inputs
  • Use <FormField>, <FormSection>, <FormActions>, <FormGrid> for form layout

​
Typography

  • Page title (h1): text-3xl font-bold (via <PageHeader>)
  • Section heading (h2): text-xl font-semibold text-slate-900 dark:text-white
  • Body: text-sm text-slate-600 dark:text-slate-400