For Developers

Architecture

Technology Stack

• Frontend: Svelte 5 with SvelteKit
• Styling: Tailwind CSS with custom components
• UI Components: shadcn-svelte component library
• Form Handling: SvelteKit Superforms with Zod validation
• State Management: Svelte 5 runes and reactive stores
• Deployment: Cloudflare Pages with Workers
• Database: Cloudflare R2 object storage
• Authentication: Cloudflare Access integration

Project Structure

src/
├── components/          # Reusable UI components
├── lib/
│   ├── types/          # TypeScript type definitions
│   │   ├── v3/         # Version 3 schemas
│   │   └── v4/         # Version 4 schemas (current)
│   ├── components/     # Application components
│   └── utils/          # Utility functions
├── routes/             # SvelteKit routes
├── content/            # Static content and documentation
└── styles/             # Global styles

Core Data Models

Location Record

The central entity that represents a physical location where cattle are managed:

interface LocationRecord {
  id: string;
  name: string;
  location?: GeolocationCoords;
  notes: JSONContent;
  cattle: Record<string, CattleRecord>;
  vaccinations: Record<string, VaccinationRecord>;
  births: Record<string, BirthRecord>;
  vaccinationTypes: VaccinationType[];
  createdAt: string;
  updatedAt: string;
}

Cattle Record

Individual cattle information:

interface CattleRecord {
  id: string;
  locationId: string;
  tag?: number;           // Ear tag number
  age?: number;           // Calculated age in months
  type?: string;          // Cattle type (e.g., "Angus", "Hereford")
  parent?: CattleRecord;  // Parent relationship
  dob?: string;           // Date of birth
  createdAt: string;
  updatedAt: string;
}

Birth Record

Documentation of new births:

interface BirthRecord {
  id: string;
  locationId: string;
  calfTag?: number;       // Calf's ear tag
  parentTag?: number;     // Parent's ear tag
  type?: string;          // Birth type
  dob?: string;           // Date of birth
  createdAt: string;
  updatedAt: string;
}

Vaccination Record

Health and vaccination tracking:

interface VaccinationRecord {
  id: string;
  locationId: string;
  date?: string;          // Vaccination date
  vaccinations: VaccinationType[]; // Types administered
  createdAt: string;
  updatedAt: string;
}

Getting Started

Prerequisites

• Node.js 18.17.1+ or 20.10.0+ or 22.11.0+
• pnpm package manager
• Cloudflare account (for deployment)

Installation

1. Clone the repository:

   git clone https://github.com/jasonkolodziej/cattlemin.git
   cd cattlemin

2. Install dependencies:

   pnpm install

3. Set up environment variables:

   cp .env.example .env
   # Configure your environment variables

4. Start the development server:

   pnpm dev

Development Commands

• pnpm dev - Start development server
• pnpm build - Build for production
• pnpm check - Type check the application
• pnpm test - Run tests
• pnpm format - Format code with Prettier
• pnpm lint - Lint code with ESLint

Data Validation

Cattlemin uses Zod schemas for robust data validation:

• Type Safety: All data is validated against TypeScript interfaces
• Runtime Validation: Zod ensures data integrity at runtime
• Form Validation: Real-time form validation with helpful error messages
• Schema Evolution: Versioned schemas (v3, v4) for backward compatibility

State Management

The application uses Svelte 5’s new runes for reactive state management:

• $state() - Local component state
• $derived() - Computed values
• $effect() - Side effects and reactions
• $bindable() - Two-way data binding

Location Context

The application provides a centralized location context for managing location-specific data:

const locationCtx = useLocationsCtx();
locationCtx.addCattle(formData);
locationCtx.addBirth(formData);
locationCtx.updateRecord(record);

Performance Optimizations

• Code Splitting: Automatic route-based code splitting
• Lazy Loading: Components loaded on demand
• Image Optimization: Optimized static assets
• Caching: Strategic caching strategies
• Bundle Analysis: Built-in bundle visualization

Testing

The application includes comprehensive testing:

• Unit Tests: Vitest for component testing
• Integration Tests: End-to-end testing
• Coverage Reports: Istanbul coverage reporting
• SonarCloud: Code quality monitoring

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Deployment

Cloudflare Pages

1. Build Configuration

   • Uses Cloudflare Pages for hosting
   • Automatic deployments from Git repository
   • Edge functions for server-side logic

2. Environment Setup

   • Configure Cloudflare Access for authentication
   • Set up R2 bucket for data storage
   • Configure environment variables

3. Deployment Commands

   pnpm run cf:build      # Build for Cloudflare
   pnpm run cf:deploy     # Deploy to Cloudflare Pages
   pnpm run cf:preview    # Preview deployment