knowfoolery/CLAUDE.md

# Know Foolery - Claude Code Project Guide

## Project Overview

Know Foolery is a cross-platform quiz game with a Go microservices backend and React/React Native frontend using Gluestack UI. This document provides guidance for future Claude Code sessions.

## Project Structure

```
knowfoolery/
├── docs/                           # Project documentation
│   ├── architecture.md             # System architecture
│   ├── api-specs.md                # API specifications
│   └── deployment.md               # Deployment guides
├── backend/                        # Go microservices
│   ├── services/                   # Individual microservices
│   │   ├── game-service/           # Game logic and session management
│   │   ├── question-service/       # Question CRUD operations
│   │   ├── user-service/           # User management
│   │   ├── leaderboard-service/    # Score and ranking logic
│   │   ├── session-service/        # Session and timer management
│   │   ├── admin-service/          # Admin panel backend
│   │   └── gateway-service/        # API gateway
│   ├── shared/                     # Shared Go packages
│   │   ├── auth/                   # JWT middleware and Zitadel integration
│   │   ├── database/               # Ent database client
│   │   ├── observability/          # Metrics and tracing
│   │   └── security/               # Security utilities
│   └── scripts/                    # Build and deployment scripts
├── frontend/                       # Cross-platform frontend
│   ├── packages/                   # Shared packages
│   │   ├── ui-components/          # Gluestack UI components
│   │   ├── shared-logic/           # Business logic
│   │   └── shared-types/           # TypeScript types
│   ├── web/                        # React web application
│   ├── mobile/                     # React Native mobile app
│   └── desktop/                    # Electron desktop app (future)
├── infrastructure/                 # Infrastructure as code
│   ├── docker/                     # Docker configurations
│   ├── kubernetes/                 # K8s manifests
│   └── monitoring/                 # Observability configs
├── tests/                          # Testing utilities
│   ├── e2e/                        # End-to-end tests
│   ├── load/                       # Performance tests
│   └── security/                   # Security tests
├── requirements.md                 # Project requirements
└── README.md                       # Setup and development guide
```

## Technology Stack

### Backend (Go)
- **Framework**: Fiber for HTTP routing
- **Database ORM**: Ent with PostgreSQL
- **Authentication**: Zitadel OAuth 2.0/OIDC
- **Observability**: Prometheus metrics, OpenTelemetry tracing
- **Communication**: gRPC for inter-service communication
- **Testing**: Go testing + testcontainers
- **Security**: Comprehensive input validation, JWT middleware

### Frontend (TypeScript)
- **Web**: React 18 with TypeScript
- **Mobile**: React Native with TypeScript
- **UI Framework**: Gluestack UI with NativeWind/Tailwind CSS
- **State Management**: React Context + useReducer
- **Testing**: Jest + React Testing Library + Playwright

### Database & Infrastructure
- **Primary Database**: PostgreSQL with Ent ORM
- **Cache**: Redis for sessions and performance
- **Authentication**: Self-hosted Zitadel
- **Deployment**: Docker + Kubernetes
- **Monitoring**: Prometheus + Grafana + Jaeger

## Key Architectural Decisions

### 1. Database Strategy
- **Development**: SQLite for fast local development
- **Testing**: PostgreSQL with testcontainers
- **Production**: PostgreSQL with high availability
- **ORM**: Ent (Facebook) for type-safe database operations
- **No Repository Pattern**: Direct Ent usage except for external APIs

### 2. Authentication Strategy
- **Local Development**: Mock JWT service
- **Production**: Self-hosted Zitadel
- **Repository Pattern**: Only for external integrations (Zitadel)
- **Security**: MFA required for admin accounts

### 3. Cross-Platform UI Strategy
- **Design System**: Gluestack UI for consistent components
- **Styling**: NativeWind/Tailwind CSS for utility-first styling
- **Code Sharing**: Same components work on web and mobile
- **Performance**: Native performance on mobile, optimized for web

## Development Guidelines

### Code Organization
```go
// Backend service structure
services/
├── game-service/
│   ├── cmd/main.go                 # Service entry point
│   ├── internal/
│   │   ├── handlers/               # HTTP handlers
│   │   ├── services/               # Business logic
│   │   └── models/                 # Ent models
│   ├── api/                        # API definitions
│   └── tests/                      # Service tests
```

```typescript
// Frontend component structure
packages/ui-components/
├── src/
│   ├── GameCard/
│   │   ├── GameCard.tsx            # Main component
│   │   ├── GameCard.test.tsx       # Tests
│   │   └── index.ts                # Exports
│   └── index.ts                    # Package exports
```

### Naming Conventions
- **Go**: PascalCase for exported, camelCase for unexported
- **TypeScript**: PascalCase for components, camelCase for functions
- **Files**: kebab-case for directories, PascalCase for components
- **Database**: snake_case for tables and columns

### Testing Standards
- **Unit Tests**: Required for all business logic
- **Integration Tests**: Required for database operations
- **E2E Tests**: Required for critical user journeys
- **Security Tests**: Required for all input validation
- **Performance Tests**: Required for high-load scenarios

## Security Requirements

### Critical Security Measures (Implemented Early)
1. **Input Validation**: All user inputs sanitized and validated
2. **SQL Injection Prevention**: Ent parameterized queries only
3. **XSS Protection**: HTML escaping and CSP headers
4. **Authentication**: JWT validation with secure middleware
5. **Rate Limiting**: Per-user and global rate limits
6. **HTTPS**: TLS encryption for all communications
7. **CORS**: Strict cross-origin policies

### Game Integrity
- **Server-Side Validation**: All game logic on backend
- **Score Verification**: Server calculates all scores
- **Session Security**: Tamper-proof session management
- **Anti-Cheating**: Multiple validation layers

## Common Commands

### Backend Development
```bash
# Start all services locally
docker-compose up -d

# Run specific service
cd backend/services/game-service
go run cmd/main.go

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

# Generate Ent code
go generate ./...
```

### Frontend Development
```bash
# Install dependencies
npm install

# Start web development
cd frontend/web
npm run dev

# Start mobile development
cd frontend/mobile
npm run ios    # or npm run android

# Run tests
npm test

# Build for production
npm run build
```

### Database Operations
```bash
# Run migrations
go run backend/scripts/migrate.go

# Reset database (development only)
go run backend/scripts/reset-db.go

# Seed test data
go run backend/scripts/seed.go
```

## Environment Configuration

### Development (.env.dev)
```bash
# Database
DATABASE_URL=sqlite://./dev.db
REDIS_URL=redis://localhost:6379

# Authentication
JWT_SECRET=dev-secret-key
ZITADEL_URL=http://localhost:8080

# Observability
PROMETHEUS_PORT=9090
JAEGER_ENDPOINT=http://localhost:14268
```

### Production (.env.prod)
```bash
# Database
DATABASE_URL=postgres://user:pass@db:5432/knowfoolery
REDIS_URL=redis://redis:6379

# Authentication
JWT_SECRET=${JWT_SECRET}
ZITADEL_URL=${ZITADEL_URL}

# Observability
PROMETHEUS_PORT=9090
JAEGER_ENDPOINT=${JAEGER_ENDPOINT}
```

## Development Workflow

### 1. Feature Development
1. Create feature branch from main
2. Implement backend service changes
3. Add comprehensive tests
4. Implement frontend components
5. Test cross-platform compatibility
6. Update documentation
7. Create pull request

### 2. Testing Checklist
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Security tests pass
- [ ] E2E tests pass
- [ ] Cross-platform UI tests pass
- [ ] Performance tests pass

### 3. Deployment Process
1. Merge to main branch
2. Automated CI/CD pipeline
3. Deploy to staging environment
4. Run smoke tests
5. Deploy to production
6. Monitor metrics and alerts

## Troubleshooting

### Common Issues

#### Database Connection Errors
```bash
# Check database status
docker-compose ps

# Reset database connection
docker-compose restart postgres

# Check logs
docker-compose logs postgres
```

#### Authentication Issues
```bash
# Verify JWT token
curl -H "Authorization: Bearer $TOKEN" localhost:8080/api/health

# Check Zitadel status
curl localhost:8080/.well-known/openid_configuration
```

#### Frontend Build Issues
```bash
# Clear node modules
rm -rf node_modules package-lock.json
npm install

# Clear build cache
npm run clean
npm run build
```

## Performance Optimization

### Backend Optimization
- Use Ent query optimization
- Implement Redis caching
- Profile with pprof
- Monitor with Prometheus

### Frontend Optimization
- Bundle size analysis
- React Native performance profiling
- Gluestack UI optimization
- Image and asset optimization

## Security Checklist

### Before Each Release
- [ ] Security dependencies updated
- [ ] Vulnerability scan passed
- [ ] Penetration testing completed
- [ ] Security headers configured
- [ ] Input validation tested
- [ ] Authentication flows verified
- [ ] Rate limiting tested
- [ ] Audit logs reviewed

## Monitoring and Alerts

### Key Metrics to Watch
- **Response Times**: API endpoint performance
- **Error Rates**: Application stability
- **Authentication**: Success/failure rates
- **Game Metrics**: Session duration, completion rates
- **Security Events**: Failed logins, rate limit hits

### Alert Conditions
- API response time > 500ms
- Error rate > 1%
- Authentication failure rate > 5%
- Database connection issues
- Security events detected

## Future Development Notes

### Mobile App Considerations
- Platform-specific optimizations needed
- App store submission requirements
- Push notification integration
- Offline capability planning

### Desktop App Considerations
- Electron performance optimization
- Native OS integration
- Auto-update mechanism
- Platform-specific packaging

### Scalability Planning
- Horizontal scaling strategies
- Database sharding considerations
- CDN integration for global reach
- Microservice boundaries refinement

This guide should be updated as the project evolves and new decisions are made.