CrittrHavens Developer Documentation 🛠️

Welcome to the technical documentation for CrittrHavens - a modern pet care management application built with React, TypeScript, and Supabase.

Hey Developer! 👩‍💻👨‍💻

Whether you're a seasoned pro or just starting your coding journey, this documentation will guide you through the CrittrHavens codebase. We've written everything in plain language with lots of examples - no computer science degree required!

🎯 Quick Start for Developers

🚀 Developer Quickstart
Core workflows and technical implementation details
💻 Set Up Your Environment
Get your development environment ready in 15 minutes
⚛️ Component Development
Build React components the right way!
💻 Architecture Overview
Understand the codebase structure

🏗️ Architecture Overview

CrittrHavens is a single-page application (SPA) built with modern web technologies:

graph TB
    subgraph "Frontend"
        A[React App] --> B[TypeScript]
        A --> C[Tailwind CSS]
        A --> D[shadcn/ui]
    end
    
    subgraph "State & Data"
        E[React Query] --> F[Supabase Client]
    end
    
    subgraph "Backend"
        F --> G[PostgreSQL]
        F --> H[Auth]
        F --> I[Storage]
        F --> J[Edge Functions]
    end
    
    A --> E

Tech Stack Explained

Technology	What It Does	Why We Use It
React 18	Builds the user interface	Industry standard, huge community
TypeScript	Adds types to JavaScript	Catches bugs before they happen
Vite	Development server & bundler	Lightning fast builds
Tailwind CSS	Utility-first styling	Consistent, responsive design
shadcn/ui	Component library	Beautiful, accessible components
React Query	Server state management	Caching, syncing, and updates
Supabase	Backend-as-a-Service	Database, auth, storage in one
Capacitor	Mobile app wrapper	Deploy to iOS/Android

📁 Project Structure

CrittrHavens/
├── src/
│   ├── components/     # Reusable UI components
│   │   ├── ui/        # Basic UI elements (buttons, cards)
│   │   ├── care/      # Care-related components
│   │   ├── inventory/ # Inventory components
│   │   └── tasks/     # Task management
│   ├── pages/         # Full page components
│   ├── hooks/         # Custom React hooks
│   ├── lib/           # Utility functions
│   └── types/         # TypeScript definitions
├── supabase/
│   ├── migrations/    # Database schema changes
│   └── functions/     # Server-side functions
└── docs/             # This documentation!

🚦 Development Workflow

1. Pick a Task Browse GitHub Issues for something to work on

2. Create Branch

git checkout -b feature/your-feature

3. Make Changes Write code, add tests, update docs

4. Test Locally

npm run dev  # Start dev server
npm test     # Run tests

5. Submit PR Push your branch and create a pull request

📚 Documentation Sections

🎓 Learning Path (Start Here If New)

Developer Quickstart - Core workflows and implementation details
Development Workflow - What you need on your computer
Component Guide - Understanding components and state
State Management - Managing application state
Testing Guide - Writing and running tests

🔧 Core Concepts

Component Architecture - How we build UI pieces
State Management - React Query patterns
Form Handling - Forms with React Hook Form
Error Handling - Graceful error recovery
Supabase Integration - Authentication and backend services

🏗️ Feature Implementation

Learn how major features work:

Care Center Architecture - Unified care management system (see also: User Care Center Guide)
Task Management Architecture - Template-instance task scheduling system (see also: User Task Guide)
Growth Tracking and Measurements - Measurement system architecture and chart implementation (see also: User Growth Tracking Guide)
Database Schema - Data model and relationships
Forms & Validation - Form handling with React Hook Form
Performance Optimization - Keep the app fast
Error Handling - Graceful error recovery
Testing Strategy - Comprehensive testing approach

🧪 Testing & Quality

Testing Strategy - Unit, integration, and E2E tests
Development Workflow - Development best practices
Performance Optimization - Keep the app fast
Error Handling - Find and fix issues

🚀 Deployment & DevOps

Development Workflow - Build and deployment process
Database Schema - Database migrations and setup
Performance Guide - Production optimization
Testing Guide - CI/CD testing strategies

💡 Key Patterns You'll See

Component Pattern

// Simple, typed functional component
interface PetCardProps {
  name: string;
  species: string;
  imageUrl?: string;
}

export function PetCard({ name, species, imageUrl }: PetCardProps) {
  return (
    <Card>
      <CardHeader>
        <h3>{name}</h3>
        <p>{species}</p>
      </CardHeader>
    </Card>
  );
}

Hook Pattern

// Custom hook for data fetching
export function usePets() {
  return useQuery({
    queryKey: ['pets'],
    queryFn: fetchPets,
  });
}

Form Pattern

// Type-safe forms with Zod
const schema = z.object({
  name: z.string().min(1),
  species: z.string(),
});

🛠️ Development Tools

Essential Tools

VS Code with extensions
React DevTools
Git & GitHub Desktop
Node.js 18+

Helpful Tools

Supabase Dashboard
Postman for API testing
Chrome DevTools
Figma for designs

🤝 Getting Help

📖 Read the Docs Start with this documentation - we've tried to cover everything!

💬 Ask Questions Open a GitHub Discussion - no question is too basic!

🐛 Report Bugs Found something broken? Create an issue

👥 Community Join other developers working on CrittrHavens

🎯 Common Developer Tasks

First Day Tasks

Set up development environment
Run the app locally
Make a small text change
Submit your first PR

Regular Tasks

Advanced Tasks

Optimize performance
Add new database tables
Create Edge Functions
Implement new features

📝 Code Philosophy

We believe in:

Readable code > clever code
User experience > developer convenience
Incremental improvements > perfect solutions
Tests > hoping it works
Documentation > tribal knowledge

🚀 Ready to Code?

Next Step: Developer Quickstart Guide →

Remember: Every expert was once a beginner. We're here to help you succeed! 💪

This documentation is kept beginner-friendly on purpose. If you're an experienced developer, you'll find advanced topics in the specific sections.