From eb47b70fbf91379f66bb849cc0ef1cf9f8f86c2e Mon Sep 17 00:00:00 2001 From: oabrivard Date: Wed, 3 Sep 2025 08:37:28 +0200 Subject: [PATCH] Initialized Claude code --- CLAUDE.md | 200 ++++++++++++++++++++ docs/index.md => README.md | 14 +- docs/3_guidelines/development-guidelines.md | 1 + 3 files changed, 208 insertions(+), 7 deletions(-) create mode 100644 CLAUDE.md rename docs/index.md => README.md (88%) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..66e668f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,200 @@ +# 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 \ No newline at end of file diff --git a/docs/index.md b/README.md similarity index 88% rename from docs/index.md rename to README.md index 0cad608..dea2bff 100644 --- a/docs/index.md +++ b/README.md @@ -26,18 +26,18 @@ Know Foolery is a quiz game inspired by the French game "Déconnaissance" (https ### Documentation #### Detailed requirements -- [Functional](1_requirements/functional-requirements.md) -- [Non Functional](1_requirements/non-functional-requirements.md) +- [Functional](docs/1_requirements/functional-requirements.md) +- [Non Functional](docs/1_requirements/non-functional-requirements.md) #### Architecture -- [Technical](2_architecture/technical-architecture.md) -- [Security](2_architecture/security-architecture.md) +- [Technical](docs/2_architecture/technical-architecture.md) +- [Security](docs/2_architecture/security-architecture.md) - [Observability](2_architecture/observability-architecture.md) #### Guidelines -- [Development](3_guidelines/development-guidelines.md) -- [Security](3_guidelines/security-guidelines.md) -- [Observability](3_guidelines/observability-guidelines.md) +- [Development](docs/3_guidelines/development-guidelines.md) +- [Security](docs/3_guidelines/security-guidelines.md) +- [Observability](docs/3_guidelines/observability-guidelines.md) ### Future Enhancements diff --git a/docs/3_guidelines/development-guidelines.md b/docs/3_guidelines/development-guidelines.md index b679296..e76db1b 100644 --- a/docs/3_guidelines/development-guidelines.md +++ b/docs/3_guidelines/development-guidelines.md @@ -27,6 +27,7 @@ This document establishes coding standards, development practices, and guideline ``` knowfoolery/ +├── docs/ # Project documentation ├── backend/ │ ├── Domain/ # Domain logic (aggregates, value objects, repositories, services from Domain Driven Design) │ ├── services/ # Microservices