Initialized Claude code
parent
f919bfb58f
commit
eb47b70fbf
@ -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
|
||||||
Loading…
Reference in New Issue