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