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

// 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

// 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

# 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

# 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

# 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)

# 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)

# 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

# Check database status
docker-compose ps

# Reset database connection
docker-compose restart postgres

# Check logs
docker-compose logs postgres

Authentication Issues

# 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

# 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.