​

System Architecture

​

High-Level Architecture

​

Component Interactions

​

User Authentication Flow

​

Booking Creation Flow

​

Data Flow: Service Listing with i18n

​

Database Schema Overview

​

Entity Relationship Diagram

​

Key Table Relationships

• User: Core user account
• Session: Active user sessions (1:N)
• Account: OAuth accounts (1:N)
• Verification: Email verification tokens

• Booking: Main booking record
• BookingPet: Junction table (Booking N:N Pet)
• BookingService: Junction table (Booking N:N Service) with pricing
• Staff: Assigned staff member (optional)

• Service.name: JSONB {"en": "Grooming", "vi": "Chăm sóc lông"}
• Service.description: JSONB with translations
• Staff position, specialization: JSONB fields
• Setting value: JSONB for multi-language configs

​

API Design Patterns

​

Standard Response Format

// Success Response
{
  "statusCode": 200,
  "message": "OK",
  "data": { /* resource data */ },
  "timestamp": "2024-01-15T10:30:00Z"
}

// Error Response
{
  "statusCode": 400,
  "message": "Bad Request",
  "error": "InvalidInput",
  "details": "Email is required",
  "timestamp": "2024-01-15T10:30:00Z"
}

​

HTTP Status Codes

​

Resource Pagination

// Request
GET /bookings?page=1&limit=20&sortBy=createdAt&sortOrder=desc

// Response
{
  "statusCode": 200,
  "data": [ /* items */ ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

​

Authentication & Authorization

​

Better Auth Integration

• Session-based authentication
• JWT tokens for API access
• Refresh token rotation
• CSRF protection on state-changing operations
• Rate limiting on auth endpoints

​

Role-Based Access Control (RBAC)

ADMIN (Full Access)
├─ All CRUD operations
├─ User & staff management
├─ Settings & configuration
└─ Audit log access

MANAGER (Limited Management)
├─ Booking management
├─ Staff scheduling
├─ Customer support
└─ Basic reporting

STAFF (Operational)
├─ View assigned bookings
├─ Update pet information
├─ Access customer notes
└─ No configuration access

CUSTOMER (Self-Service)
├─ Create/manage bookings
├─ Pet management
├─ View booking history
└─ No staff/config access

​

Deployment Architecture

​

Development Environment

localhost:3000 (Frontend Dev Server)
localhost:3001 (Backend Dev Server)
localhost:5432 (PostgreSQL)

​

Production Environment

​

Security Architecture

​

Network Security

• HTTPS/TLS 1.3+ for all communications
• CORS configured for specific origins
• Rate limiting per IP/endpoint
• DDoS protection via CDN

​

Data Security

• Passwords hashed with bcrypt
• Sessions encrypted
• Sensitive data excluded from logs
• SQL injection prevention via ORM
• XSS prevention via React escaping

​

Authentication Security

• Secure cookie flags (HttpOnly, Secure)
• CSRF tokens on state-changing operations
• Session timeout with warnings
• Account lockout after failed attempts
• Email verification for sign-up

​

Scalability Considerations

​

Current Architecture

• Monolithic backend suitable for < 1000 bookings/day
• Single database instance with replication
• Static asset CDN for frontend

​

Future Scaling

1. Horizontal Scaling: Multiple backend instances behind load balancer
2. Database: Query optimization, read replicas, eventual sharding
3. Caching: Redis for sessions and frequent queries
4. Message Queue: Async booking notifications and processing
5. Microservices: Separate booking, payment, notification services

​

Related Documentation