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

# 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

# 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

# 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