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