knowfoolery/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Know Foolery is a cross-platform quiz game inspired by the French game "Déconnaissance". The project follows a microservices architecture with Go backend services and React/React Native frontends using Gluestack UI for consistent cross-platform design.

## Architecture

### Backend Structure
- **Microservices**: Go-based services using Fiber 3.0+ framework
- **Database ORM**: Ent (Facebook) for type-safe database operations  
- **Communication**: gRPC for inter-service communication
- **Authentication**: JWT + Zitadel Integration (OAuth 2.0/OIDC)
- **Database**: PostgreSQL (production), SQLite (development/testing)
- **Cache**: Redis for sessions and rate limiting

### Service Architecture
```
backend/
├── Domain/                     # Domain logic (DDD patterns)
├── services/                   # Microservices
│   ├── {service-name}/
│   │   ├── cmd/main.go         # Service entry point
│   │   ├── internal/
│   │   │   ├── handlers/       # Fiber HTTP handlers
│   │   │   ├── app/            # Business logic
│   │   │   ├── middleware/     # Service-specific middleware
│   │   │   └── models/         # Ent models and schemas
│   │   ├── config/             # Configuration management
│   │   └── tests/              # Service-specific tests
│   └── shared/                 # Shared packages
│       ├── auth/               # JWT & Zitadel integration
│       ├── database/           # Ent database client
│       ├── observability/      # Metrics and tracing
│       └── security/           # Security utilities
```

### Core Services
1. **Game Service** (port 8080): Session management, scoring logic
2. **Question Service** (port 8081): CRUD operations for questions/themes  
3. **User Service** (port 8082): Player registration and profiles
4. **Leaderboard Service** (port 8083): Score calculations and rankings
5. **Session Service** (port 8084): Timer management, session state
6. **Admin Service** (port 8085): Question/user management with OAuth
7. **Gateway Service** (port 8086): API routing, authentication, rate limiting

### Frontend Structure
```
frontend/
├── packages/
│   ├── ui-components/          # Shared Gluestack UI components
│   ├── shared-logic/           # Business logic
│   ├── shared-types/           # TypeScript types
│   └── shared-utils/           # Utility functions
└── apps/
    ├── web/                    # React web app (Vite + TypeScript)
    ├── mobile/                 # React Native app (Expo)
    └── desktop/                # Wails desktop app
```

## Development Commands

### Backend Development
```bash
# Navigate to service directory first
cd backend/services/{service-name}

# Start service in development mode with hot reload
go run cmd/main.go

# Run tests for a specific service
go test ./... -v

# Run tests with coverage
go test ./... -cover

# Build service binary
go build -o bin/{service-name} cmd/main.go

# Generate Ent schemas (from service root)
go generate ./...

# Lint Go code
golangci-lint run

# Format Go code  
go fmt ./...
goimports -w .
```

### Development Environment
```bash
# Start development stack with Docker Compose
cd infrastructure/dev
docker-compose up -d

# This starts:
# - PostgreSQL database (port 5432)
# - Redis cache (port 6379) 
# - Zitadel auth server (port 8080)
```

### Frontend Development
```bash
# Web application
cd frontend/apps/web
npm install
npm run dev          # Start development server
npm run build        # Production build
npm run test         # Run Jest tests
npm run lint         # ESLint
npm run type-check   # TypeScript checking

# Mobile application  
cd frontend/apps/mobile
npm install
npx expo start       # Start Expo development
npx expo run:ios     # Run on iOS simulator
npx expo run:android # Run on Android emulator

# Desktop application
cd frontend/apps/desktop
npm install
npm run dev          # Start Wails development
npm run build        # Build desktop app
```

## Key Technical Patterns

### Go Service Structure
- Services use Fiber v3 framework with structured error handling
- Business logic separated into service layer with dependency injection
- Ent ORM with schema-first approach and proper indexing
- Custom middleware for JWT authentication and rate limiting
- Comprehensive testing with testcontainers for integration tests

### TypeScript/React Patterns
- Components use Gluestack UI with proper TypeScript typing
- Custom hooks pattern for business logic (e.g., `useGameSession`)
- Context + useReducer for state management
- Comprehensive testing with Jest + React Testing Library

### Authentication Flow
- Zitadel provides OAuth 2.0/OIDC authentication
- JWT tokens validated via shared auth middleware
- User context stored in Fiber locals for request handling
- Admin routes protected with role-based authorization

### Database Design
- Domain-driven design with clear aggregate boundaries
- Ent schemas with proper validation and indexes
- Transaction management for multi-step operations
- Separate read/write patterns for performance

## Game Logic

### Core Gameplay Rules
- Players have exactly 3 attempts per question
- 30-minute maximum session time
- Scoring: 2 points (no hint), 1 point (with hint), 0 points (incorrect/timeout)
- Questions belong to themes (Geography, History, Science, etc.)
- Leaderboard shows top 10 scores

### Session Management
- Active session checking prevents duplicate games
- Timer implemented with Redis-backed state
- Session timeout handling with proper cleanup
- Score calculation with attempt and hint tracking

## Testing Strategy

### Backend Testing
- Unit tests with Go testing framework + testify
- Integration tests with testcontainers (PostgreSQL)
- Service layer tests with mocked dependencies
- API endpoint tests with Fiber test utilities

### Frontend Testing  
- Component tests with Jest + React Testing Library
- Hook tests with @testing-library/react-hooks
- E2E tests with Playwright
- Visual regression testing for UI components

## Security Considerations

- JWT token validation on all protected endpoints
- Rate limiting per user and IP address
- Input validation and sanitization
- CORS configuration for cross-origin requests
- SQL injection prevention with Ent ORM
- Secrets management via environment variables

## Documentation Structure

The `docs/` directory contains comprehensive documentation:
- **Requirements**: Functional and non-functional specifications
- **Architecture**: Technical, security, and observability designs  
- **Guidelines**: Development, security, and observability standards