> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sagozen.digital/llms.txt
> Use this file to discover all available pages before exploring further.

# Codebase Summary

> Project structure, architecture overview, and key modules for Pet Service Management System

# Codebase Summary

Overview of the Pet Service Management System codebase structure and organization.

## Project Overview

Full-stack web application for managing pet services: boarding, grooming, veterinary care, training, daycare, transportation.

<CardGroup cols={3}>
  <Card title="Frontend" icon="react">
    Next.js 16.0.10 + React 19.2.1
  </Card>

  <Card title="Backend" icon="server">
    NestJS 11.0.1 + PostgreSQL
  </Card>

  <Card title="Type Safety" icon="shield">
    TypeScript 5 Strict Mode
  </Card>
</CardGroup>

***

## Directory Structure

<Tabs>
  <Tab title="Backend">
    ```
    backend/
    ├── src/
    │   ├── auth/              # Authentication & authorization
    │   │   ├── guards/        # Auth, Admin guards
    │   │   ├── auth.controller.ts
    │   │   ├── auth.service.ts
    │   │   └── auth.module.ts
    │   ├── bookings/          # Booking management
    │   │   ├── dto/           # Data transfer objects
    │   │   ├── bookings.controller.ts
    │   │   ├── bookings.service.ts
    │   │   └── bookings.module.ts
    │   ├── services/          # Service catalog
    │   ├── staff/             # Staff management
    │   ├── settings/          # Configuration
    │   ├── dashboard/         # Analytics
    │   ├── prisma/            # Database service
    │   └── main.ts            # Entry point
    ├── prisma/
    │   ├── schema.prisma      # Database schema
    │   └── seed.ts            # Database seeding
    └── test/                  # E2E tests
    ```
  </Tab>

  <Tab title="Frontend">
    ```
    frontend/
    ├── app/
    │   ├── [locale]/          # i18n routing
    │   │   ├── (marketing)/   # Public pages
    │   │   │   ├── booking/
    │   │   │   ├── services/
    │   │   │   ├── contact/
    │   │   │   └── page.tsx
    │   │   ├── dashboard/     # Protected pages
    │   │   │   ├── booking/
    │   │   │   ├── services/
    │   │   │   ├── staff/
    │   │   │   ├── settings/
    │   │   │   └── page.tsx
    │   │   ├── login/
    │   │   ├── register/
    │   │   └── layout.tsx
    │   └── api/               # API routes
    ├── components/            # React components
    ├── lib/                   # Utilities & clients
    │   ├── api/               # API clients
    │   ├── auth-client.ts
    │   └── transformers.ts
    ├── types/                 # TypeScript types
    ├── messages/              # i18n translations (10 languages)
    └── public/                # Static assets
    ```
  </Tab>

  <Tab title="Documentation">
    ```
    docs/
    ├── project-overview-pdr.md
    ├── system-architecture.md
    ├── codebase-summary.md
    ├── code-standards.md
    ├── design-guidelines.md
    ├── project-roadmap.md
    └── i18n-implementation.md
    ```
  </Tab>
</Tabs>

***

## Backend Architecture

### Core Modules

<AccordionGroup>
  <Accordion title="auth/ - Authentication & Authorization">
    * Better Auth integration
    * Admin guard for role-based access
    * Authentication guard for protected routes
    * JWT token management
  </Accordion>

  <Accordion title="bookings/ - Booking Management">
    * Pet service bookings with status tracking
    * Multiple pets per booking support
    * Status workflow: PENDING → CONFIRMED → IN\_PROGRESS → COMPLETED → CANCELLED
    * Pricing calculations and payment tracking
  </Accordion>

  <Accordion title="services/ - Service Catalog">
    * 6 categories: BOARDING, GROOMING, VETERINARY, TRAINING, DAYCARE, TRANSPORT
    * Multi-language support (JSONB fields)
    * Pricing by unit (per day/hour/session)
    * Images and descriptions
  </Accordion>

  <Accordion title="staff/ - Staff Management">
    * Employee scheduling and availability
    * Staff-service proficiency mapping (1-5 skill levels)
    * Performance metrics (ratings, booking counts)
    * Working hours management
  </Accordion>

  <Accordion title="settings/ - Configuration">
    * Key-value store with type support
    * Grouped settings (GENERAL, PAYMENT, CONTACT)
    * Application-wide configuration
  </Accordion>

  <Accordion title="dashboard/ - Analytics">
    * Business metrics and statistics
    * User activity monitoring
    * Performance reports
  </Accordion>

  <Accordion title="prisma/ - Database Service">
    * Database operations via Prisma ORM
    * Connection management
    * Query optimization
  </Accordion>
</AccordionGroup>

### Database Schema

**User & Authentication:**

* User (Better Auth compatible)
* Session (session management)
* Account (OAuth accounts)
* Verification (email verification)

**Pet Management:**

* Pet (medical history, allergies, vaccinations)
* Species: DOG, CAT, BIRD, RABBIT, OTHER

**Services:**

* Service (catalog with JSONB multi-language fields)
* Categories: BOARDING, GROOMING, VETERINARY, TRAINING, DAYCARE, TRANSPORT

**Bookings:**

* Booking (status tracking, pricing)
* BookingPet (many-to-many: bookings to pets)
* BookingService (many-to-many: bookings to services)
* Status: PENDING, CONFIRMED, IN\_PROGRESS, COMPLETED, CANCELLED

**Staff:**

* Staff (employee details, availability)
* StaffService (staff-service mapping with proficiency)

**System:**

* Setting (configuration store)
* AuditLog (user actions, entity changes)

**Roles:**
ADMIN, MANAGER, STAFF, CUSTOMER

### API Endpoints

<Tabs>
  <Tab title="Authentication">
    ```
    POST   /auth/login
    POST   /auth/register
    POST   /auth/logout
    GET    /auth/session
    ```
  </Tab>

  <Tab title="Services">
    ```
    GET    /services
    GET    /services/:id
    POST   /services (admin)
    PUT    /services/:id (admin)
    DELETE /services/:id (admin)
    ```
  </Tab>

  <Tab title="Bookings">
    ```
    GET    /bookings
    GET    /bookings/:id
    POST   /bookings
    PUT    /bookings/:id
    DELETE /bookings/:id
    PATCH  /bookings/:id/status
    ```
  </Tab>

  <Tab title="Staff & Settings">
    ```
    GET    /staff
    GET    /staff/:id
    POST   /staff (manager)

    GET    /settings
    PUT    /settings (admin)

    GET    /dashboard/stats
    GET    /dashboard/analytics
    ```
  </Tab>
</Tabs>

***

## Frontend Architecture

### Routing Structure

**App Router with i18n:**

* Dynamic locale parameter: `[locale]/`
* Supported locales: en, de, fr, ko, ja, vi, lo, km, my, fil

**Public Routes:**

* `/[locale]/` - Home page
* `/[locale]/services` - Service listing
* `/[locale]/booking` - Booking flow
* `/[locale]/contact` - Contact page
* `/[locale]/login` - Login
* `/[locale]/register` - Registration

**Protected Routes:**

* `/[locale]/dashboard` - Dashboard overview
* `/[locale]/dashboard/booking` - Booking management
* `/[locale]/dashboard/services` - Service management
* `/[locale]/dashboard/staff` - Staff management
* `/[locale]/dashboard/settings` - Settings

### Component Architecture

**Layout Components:**

* Header.tsx - Navigation header
* Footer.tsx - Footer with contact
* DashboardHeader.tsx - Dashboard header
* LanguageSwitcher.tsx - Language selection

**Utilities:**

* lib/api/ - API client functions
* lib/auth-client.ts - Better Auth config
* lib/auth-helpers.ts - Auth utilities
* lib/transformers.ts - Data transformation

### Multi-Language Support

**next-intl Implementation:**

* 10 language support with JSON message files
* Dynamic language switching
* Locale-aware routing

**Languages:** en, de, fr, ko, ja, vi, lo, km, my, fil

***

## Technology Stack

<Tabs>
  <Tab title="Backend">
    | Package     | Version | Purpose           |
    | ----------- | ------- | ----------------- |
    | NestJS      | ^11.0.1 | Backend framework |
    | Prisma      | ^5.22.0 | ORM               |
    | Better Auth | ^1.4.7  | Authentication    |
    | TypeScript  | ^5.7.3  | Type safety       |
  </Tab>

  <Tab title="Frontend">
    | Package      | Version | Purpose            |
    | ------------ | ------- | ------------------ |
    | Next.js      | 16.0.10 | Frontend framework |
    | React        | 19.2.1  | UI library         |
    | Tailwind CSS | ^4      | Styling            |
    | next-intl    | ^4.6.0  | i18n               |
    | Plotly.js    | ^3.3.1  | Data viz           |
  </Tab>
</Tabs>

***

## Development Patterns

### Backend

* Feature-based modules (Auth, Bookings, Services)
* Each module: controller, service, module files
* DTOs for request/response validation
* Guards for authentication/authorization

### Frontend

* Functional components with hooks
* Layout components for shared UI
* Page components for routes
* Typed API client functions

***

## Build & Deployment

<CodeGroup>
  ```bash Backend theme={null}
  npm run build          # Build
  npm run start:dev      # Development
  npm run start:prod     # Production
  npm run prisma:generate # Generate Prisma client
  npm run prisma:db:push # Apply schema
  ```

  ```bash Frontend theme={null}
  npm run dev    # Development
  npm run build  # Production build
  npm run start  # Production server
  npm run lint   # ESLint
  ```
</CodeGroup>

***

<CardGroup cols={2}>
  <Card title="Code Standards" icon="code" href="/code-standards">
    View coding conventions
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/architecture">
    System architecture
  </Card>

  <Card title="Installation" icon="download" href="/installation">
    Setup guide
  </Card>

  <Card title="Back to Home" icon="home" href="/">
    Return to homepage
  </Card>
</CardGroup>