Updated documentaion
parent
b4f03f9a77
commit
f919bfb58f
@ -1,369 +0,0 @@
|
|||||||
# 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 ~/Projects/go/src/knowfoolery/backend/services/game-service
|
|
||||||
go run cmd/main.go
|
|
||||||
|
|
||||||
# Run tests with coverage
|
|
||||||
go test -v -cover ./...
|
|
||||||
|
|
||||||
# Generate Ent code
|
|
||||||
cd ~/Projects/go/src/knowfoolery/database/ent
|
|
||||||
go run -mod=mod entgo.io/ent/cmd/ent describe ./schema
|
|
||||||
|
|
||||||
# Update database schema description from Ent code
|
|
||||||
cd ~/Projects/go/src/knowfoolery/database/ent
|
|
||||||
go run -mod=mod entgo.io/ent/cmd/ent describe ./schema > ./schema/schema.md
|
|
||||||
```
|
|
||||||
|
|
||||||
### Frontend Development
|
|
||||||
```bash
|
|
||||||
# Install dependencies
|
|
||||||
npm install
|
|
||||||
|
|
||||||
# Start web development
|
|
||||||
cd ~/Projects/go/src/knowfoolery/frontend/web
|
|
||||||
npm run dev
|
|
||||||
|
|
||||||
# Start mobile development
|
|
||||||
cd ~/Projects/go/src/knowfoolery/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 ~/Projects/go/src/knowfoolery/backend/scripts/migrate.go
|
|
||||||
|
|
||||||
# Reset database (development only)
|
|
||||||
go run ~/Projects/go/src/knowfoolery/backend/scripts/reset-db.go
|
|
||||||
|
|
||||||
# Seed test data
|
|
||||||
go run ~/Projects/go/src/knowfoolery/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 domain model changes
|
|
||||||
3. Add comprehensive tests for domain model
|
|
||||||
3. Implement database and ORM changes
|
|
||||||
3. Add comprehensive tests for domain model
|
|
||||||
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.
|
|
||||||
@ -1,392 +0,0 @@
|
|||||||
# Progressive Phase 1 Implementation Plan: Incremental Infrastructure Setup
|
|
||||||
|
|
||||||
## Overview
|
|
||||||
Instead of setting up all infrastructure at once, we'll progressively build Phase 1 in three distinct sub-phases, allowing for thorough testing and validation at each layer before adding complexity.
|
|
||||||
|
|
||||||
## Phase 1A: Backend + Database Foundation (5-7 days)
|
|
||||||
|
|
||||||
### Core Infrastructure Setup
|
|
||||||
**Dependencies: None**
|
|
||||||
|
|
||||||
**1A.1 Go Project Structure & Basic Services**
|
|
||||||
- Create complete Go module structure for all microservices
|
|
||||||
- Implement basic Fiber apps with health endpoints for each service
|
|
||||||
- Set up shared packages structure (auth, database, observability, security)
|
|
||||||
- Create basic service discovery and configuration management
|
|
||||||
- Add graceful shutdown and signal handling
|
|
||||||
|
|
||||||
**1A.2 Database Layer with Ent**
|
|
||||||
- Define complete Ent schemas (Question, GameSession, QuestionAttempt)
|
|
||||||
- Set up dual database configuration (SQLite for dev, PostgreSQL for testing)
|
|
||||||
- Create migration scripts and database initialization
|
|
||||||
- Implement basic CRUD operations for each entity
|
|
||||||
- Add database connection pooling and health checks
|
|
||||||
|
|
||||||
**1A.3 Mock Authentication System**
|
|
||||||
- Create simple JWT-based mock authentication (no external calls)
|
|
||||||
- Implement basic role-based access control (player/admin)
|
|
||||||
- Add middleware for token validation using local secret
|
|
||||||
- Create user context propagation through services
|
|
||||||
- Add basic security headers and CORS
|
|
||||||
|
|
||||||
**1A.4 Basic Docker Environment**
|
|
||||||
- Create `docker-compose.basic.yml` with only PostgreSQL
|
|
||||||
- Add database initialization and seeding containers
|
|
||||||
- Create health check scripts for database connectivity
|
|
||||||
- Set up volume management for persistent data
|
|
||||||
|
|
||||||
**1A.5 Integration Testing Framework**
|
|
||||||
- Set up testcontainers for PostgreSQL integration tests
|
|
||||||
- Create test utilities for database seeding and cleanup
|
|
||||||
- Implement service-level integration tests
|
|
||||||
- Add API endpoint testing with mock authentication
|
|
||||||
- Create test data factories and fixtures
|
|
||||||
|
|
||||||
**Success Criteria for 1A:**
|
|
||||||
- All services start and respond to health checks
|
|
||||||
- Database migrations run successfully
|
|
||||||
- Mock authentication validates tokens correctly
|
|
||||||
- Integration tests pass with PostgreSQL container
|
|
||||||
- Services can perform basic CRUD operations
|
|
||||||
- Docker environment runs consistently
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 1B: Add Redis Layer (2-3 days)
|
|
||||||
|
|
||||||
### Redis Integration
|
|
||||||
**Dependencies: Phase 1A complete**
|
|
||||||
|
|
||||||
**1B.1 Redis Configuration & Connection**
|
|
||||||
- Add Redis client to shared package with connection pooling
|
|
||||||
- Create Redis health checks and monitoring
|
|
||||||
- Implement connection retry logic and circuit breaker
|
|
||||||
- Add Redis configuration management (cluster vs single instance)
|
|
||||||
|
|
||||||
**1B.2 Session Management with Redis**
|
|
||||||
- Migrate session storage from in-memory to Redis
|
|
||||||
- Implement session middleware with Redis backend
|
|
||||||
- Add session invalidation and cleanup routines
|
|
||||||
- Create session security (encryption, tampering protection)
|
|
||||||
|
|
||||||
**1B.3 Caching Layer Implementation**
|
|
||||||
- Create cache abstraction layer for future use
|
|
||||||
- Add caching for frequently accessed data (questions, leaderboards)
|
|
||||||
- Implement cache invalidation strategies
|
|
||||||
- Add cache performance metrics
|
|
||||||
|
|
||||||
**1B.4 Update Development Environment**
|
|
||||||
- Extend `docker-compose.basic.yml` to include Redis
|
|
||||||
- Create `docker-compose.redis.yml` configuration
|
|
||||||
- Update health check scripts to verify Redis connectivity
|
|
||||||
- Add Redis monitoring and debugging tools
|
|
||||||
|
|
||||||
**1B.5 Redis Integration Testing**
|
|
||||||
- Extend integration tests to include Redis functionality
|
|
||||||
- Test session persistence across service restarts
|
|
||||||
- Validate cache behavior and invalidation
|
|
||||||
- Test Redis failover scenarios
|
|
||||||
- Add performance testing for cache operations
|
|
||||||
|
|
||||||
**Success Criteria for 1B:**
|
|
||||||
- Redis connects reliably with proper failover
|
|
||||||
- Sessions persist correctly in Redis
|
|
||||||
- Cache operations perform as expected
|
|
||||||
- Integration tests pass with Redis + PostgreSQL
|
|
||||||
- Services handle Redis connectivity issues gracefully
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Phase 1C: Add Zitadel Authentication (3-4 days)
|
|
||||||
|
|
||||||
### External Authentication Integration
|
|
||||||
**Dependencies: Phase 1B complete**
|
|
||||||
|
|
||||||
**1C.1 Zitadel Repository Implementation**
|
|
||||||
- Implement full ZitadelRepository interface with HTTP client
|
|
||||||
- Add JWT token validation with Zitadel public keys
|
|
||||||
- Create token refresh and user management functionality
|
|
||||||
- Implement circuit breaker for external API calls
|
|
||||||
- Add proper error handling and retry logic
|
|
||||||
|
|
||||||
**1C.2 Replace Mock Authentication**
|
|
||||||
- Migrate from mock JWT to real Zitadel integration
|
|
||||||
- Update middleware to validate tokens against Zitadel
|
|
||||||
- Implement proper role and permission mapping
|
|
||||||
- Add MFA validation for admin endpoints
|
|
||||||
- Create user context enrichment from Zitadel claims
|
|
||||||
|
|
||||||
**1C.3 Complete Docker Environment**
|
|
||||||
- Add Zitadel container to Docker Compose setup
|
|
||||||
- Create `docker-compose.yml` with full infrastructure stack
|
|
||||||
- Configure Zitadel with proper OAuth applications
|
|
||||||
- Set up development user accounts and roles
|
|
||||||
- Add monitoring for all services
|
|
||||||
|
|
||||||
**1C.4 Observability Foundation**
|
|
||||||
- Add Prometheus metrics collection to all services
|
|
||||||
- Create basic Grafana dashboards
|
|
||||||
- Implement distributed tracing preparation
|
|
||||||
- Add structured logging across services
|
|
||||||
- Create alerting for critical failures
|
|
||||||
|
|
||||||
**1C.5 End-to-End Integration Testing**
|
|
||||||
- Create full authentication flow tests
|
|
||||||
- Test token validation and refresh cycles
|
|
||||||
- Validate role-based access control
|
|
||||||
- Test multi-service communication with real auth
|
|
||||||
- Add performance testing under load
|
|
||||||
|
|
||||||
**Success Criteria for 1C:**
|
|
||||||
- Zitadel authentication works end-to-end
|
|
||||||
- All services integrate properly with real JWT validation
|
|
||||||
- Role-based access control functions correctly
|
|
||||||
- Integration tests pass with full infrastructure stack
|
|
||||||
- System handles authentication failures gracefully
|
|
||||||
- Basic observability provides useful insights
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Progressive Testing Strategy
|
|
||||||
|
|
||||||
### Phase 1A Testing Focus
|
|
||||||
- Database operations and data consistency
|
|
||||||
- Service startup and health check reliability
|
|
||||||
- Mock authentication token flows
|
|
||||||
- Basic API functionality
|
|
||||||
|
|
||||||
### Phase 1B Testing Focus
|
|
||||||
- Redis connectivity and session persistence
|
|
||||||
- Cache performance and invalidation
|
|
||||||
- Service behavior with Redis failures
|
|
||||||
- Session security and tampering protection
|
|
||||||
|
|
||||||
### Phase 1C Testing Focus
|
|
||||||
- External authentication integration
|
|
||||||
- Token validation and refresh flows
|
|
||||||
- Role-based access across services
|
|
||||||
- System resilience under auth failures
|
|
||||||
- End-to-end user workflows
|
|
||||||
|
|
||||||
## Benefits of Progressive Approach
|
|
||||||
|
|
||||||
1. **Incremental Complexity**: Each phase adds one major component
|
|
||||||
2. **Isolation of Issues**: Problems can be traced to specific layers
|
|
||||||
3. **Thorough Testing**: Each layer gets comprehensive validation
|
|
||||||
4. **Rollback Capability**: Can revert to previous working state
|
|
||||||
5. **Learning Curve**: Understand each technology deeply before combining
|
|
||||||
6. **Debugging Ease**: Fewer variables when troubleshooting
|
|
||||||
7. **Confidence Building**: Success at each phase builds momentum
|
|
||||||
|
|
||||||
## Deliverables Timeline
|
|
||||||
|
|
||||||
- **Week 1**: Phase 1A - Backend + Database foundation
|
|
||||||
- **Week 2**: Phase 1B - Redis integration and testing
|
|
||||||
- **Week 2-3**: Phase 1C - Zitadel integration and full stack testing
|
|
||||||
|
|
||||||
This progressive approach ensures solid foundations at each layer before adding the next level of complexity, making the overall implementation more reliable and maintainable.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Detailed Implementation Steps for Phase 1A
|
|
||||||
|
|
||||||
### Step 1A.1: Create Go Project Structure
|
|
||||||
|
|
||||||
#### Root Go Module Setup
|
|
||||||
```bash
|
|
||||||
# Initialize main go.mod
|
|
||||||
go mod init knowfoolery
|
|
||||||
go mod tidy
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Directory Structure Creation
|
|
||||||
```
|
|
||||||
knowfoolery/
|
|
||||||
├── backend/
|
|
||||||
│ ├── services/
|
|
||||||
│ │ ├── game-service/
|
|
||||||
│ │ │ ├── cmd/main.go
|
|
||||||
│ │ │ ├── internal/
|
|
||||||
│ │ │ │ ├── handlers/
|
|
||||||
│ │ │ │ ├── services/
|
|
||||||
│ │ │ │ ├── middleware/
|
|
||||||
│ │ │ │ └── models/
|
|
||||||
│ │ │ ├── config/
|
|
||||||
│ │ │ ├── tests/
|
|
||||||
│ │ │ └── go.mod
|
|
||||||
│ │ ├── question-service/
|
|
||||||
│ │ ├── user-service/
|
|
||||||
│ │ ├── leaderboard-service/
|
|
||||||
│ │ ├── session-service/
|
|
||||||
│ │ ├── admin-service/
|
|
||||||
│ │ └── gateway-service/
|
|
||||||
│ ├── shared/
|
|
||||||
│ │ ├── auth/
|
|
||||||
│ │ ├── database/
|
|
||||||
│ │ ├── observability/
|
|
||||||
│ │ ├── security/
|
|
||||||
│ │ └── utils/
|
|
||||||
│ └── scripts/
|
|
||||||
└── infrastructure/
|
|
||||||
└── docker/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Step 1A.2: Define Ent Schemas
|
|
||||||
|
|
||||||
#### Question Schema
|
|
||||||
```go
|
|
||||||
// backend/shared/database/ent/schema/question.go
|
|
||||||
package schema
|
|
||||||
|
|
||||||
import (
|
|
||||||
"time"
|
|
||||||
"entgo.io/ent"
|
|
||||||
"entgo.io/ent/schema/field"
|
|
||||||
"entgo.io/ent/schema/index"
|
|
||||||
)
|
|
||||||
|
|
||||||
type Question struct {
|
|
||||||
ent.Schema
|
|
||||||
}
|
|
||||||
|
|
||||||
func (Question) Fields() []ent.Field {
|
|
||||||
return []ent.Field{
|
|
||||||
field.String("id").Unique(),
|
|
||||||
field.String("theme").NotEmpty(),
|
|
||||||
field.Text("text").NotEmpty(),
|
|
||||||
field.String("answer").NotEmpty(),
|
|
||||||
field.Text("hint").Optional(),
|
|
||||||
field.Enum("difficulty").Values("easy", "medium", "hard").Default("medium"),
|
|
||||||
field.Bool("is_active").Default(true),
|
|
||||||
field.Time("created_at").Default(time.Now),
|
|
||||||
field.Time("updated_at").Default(time.Now).UpdateDefault(time.Now),
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
func (Question) Indexes() []ent.Index {
|
|
||||||
return []ent.Index{
|
|
||||||
index.Fields("theme"),
|
|
||||||
index.Fields("difficulty"),
|
|
||||||
index.Fields("is_active"),
|
|
||||||
index.Fields("created_at"),
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Step 1A.3: Basic Service Implementation
|
|
||||||
|
|
||||||
#### Game Service Main
|
|
||||||
```go
|
|
||||||
// backend/services/game-service/cmd/main.go
|
|
||||||
package main
|
|
||||||
|
|
||||||
import (
|
|
||||||
"log"
|
|
||||||
"github.com/gofiber/fiber/v2"
|
|
||||||
"github.com/gofiber/fiber/v2/middleware/cors"
|
|
||||||
"github.com/gofiber/fiber/v2/middleware/logger"
|
|
||||||
)
|
|
||||||
|
|
||||||
func main() {
|
|
||||||
app := fiber.New(fiber.Config{
|
|
||||||
AppName: "Know Foolery Game Service",
|
|
||||||
})
|
|
||||||
|
|
||||||
// Middleware
|
|
||||||
app.Use(logger.New())
|
|
||||||
app.Use(cors.New())
|
|
||||||
|
|
||||||
// Health endpoint
|
|
||||||
app.Get("/health", func(c *fiber.Ctx) error {
|
|
||||||
return c.JSON(fiber.Map{
|
|
||||||
"status": "healthy",
|
|
||||||
"service": "game-service",
|
|
||||||
})
|
|
||||||
})
|
|
||||||
|
|
||||||
log.Println("Game Service starting on :3001")
|
|
||||||
log.Fatal(app.Listen(":3001"))
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### Step 1A.4: Docker Compose Basic Setup
|
|
||||||
|
|
||||||
#### Basic Docker Compose
|
|
||||||
```yaml
|
|
||||||
# infrastructure/docker/docker-compose.basic.yml
|
|
||||||
version: '3.8'
|
|
||||||
|
|
||||||
services:
|
|
||||||
postgres:
|
|
||||||
image: postgres:15-alpine
|
|
||||||
environment:
|
|
||||||
POSTGRES_DB: knowfoolery
|
|
||||||
POSTGRES_USER: knowfoolery
|
|
||||||
POSTGRES_PASSWORD: dev-password
|
|
||||||
ports:
|
|
||||||
- "5432:5432"
|
|
||||||
volumes:
|
|
||||||
- postgres_data:/var/lib/postgresql/data
|
|
||||||
- ./init-db.sql:/docker-entrypoint-initdb.d/init-db.sql
|
|
||||||
healthcheck:
|
|
||||||
test: ["CMD-SHELL", "pg_isready -U knowfoolery"]
|
|
||||||
interval: 10s
|
|
||||||
timeout: 5s
|
|
||||||
retries: 5
|
|
||||||
|
|
||||||
volumes:
|
|
||||||
postgres_data:
|
|
||||||
```
|
|
||||||
|
|
||||||
### Step 1A.5: Integration Test Framework
|
|
||||||
|
|
||||||
#### Test Utilities
|
|
||||||
```go
|
|
||||||
// backend/shared/database/testutil/testutil.go
|
|
||||||
package testutil
|
|
||||||
|
|
||||||
import (
|
|
||||||
"context"
|
|
||||||
"testing"
|
|
||||||
"github.com/testcontainers/testcontainers-go"
|
|
||||||
"github.com/testcontainers/testcontainers-go/modules/postgres"
|
|
||||||
)
|
|
||||||
|
|
||||||
func SetupTestDB(t *testing.T) (*ent.Client, func()) {
|
|
||||||
ctx := context.Background()
|
|
||||||
|
|
||||||
postgresContainer, err := postgres.RunContainer(ctx,
|
|
||||||
testcontainers.WithImage("postgres:15-alpine"),
|
|
||||||
postgres.WithDatabase("testdb"),
|
|
||||||
postgres.WithUsername("test"),
|
|
||||||
postgres.WithPassword("test"),
|
|
||||||
)
|
|
||||||
if err != nil {
|
|
||||||
t.Fatal(err)
|
|
||||||
}
|
|
||||||
|
|
||||||
// Get connection string and create Ent client
|
|
||||||
// ... implementation details
|
|
||||||
|
|
||||||
cleanup := func() {
|
|
||||||
postgresContainer.Terminate(ctx)
|
|
||||||
}
|
|
||||||
|
|
||||||
return client, cleanup
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Current Phase 1A Implementation Checklist
|
|
||||||
|
|
||||||
- [ ] Create complete Go project structure
|
|
||||||
- [ ] Initialize all service modules with basic Fiber apps
|
|
||||||
- [ ] Define and generate all Ent schemas
|
|
||||||
- [ ] Set up database connection and migration utilities
|
|
||||||
- [ ] Implement mock JWT authentication
|
|
||||||
- [ ] Create Docker Compose basic environment
|
|
||||||
- [ ] Set up integration testing framework
|
|
||||||
- [ ] Add health checks and basic monitoring
|
|
||||||
- [ ] Create database seeding scripts
|
|
||||||
- [ ] Validate all services start and communicate properly
|
|
||||||
|
|
||||||
This detailed plan provides clear, actionable steps for implementing Phase 1A while maintaining the progressive approach that allows for thorough testing at each layer.
|
|
||||||
@ -1,157 +0,0 @@
|
|||||||
# Know Foolery - Claude Implementation Plan
|
|
||||||
|
|
||||||
## Project Overview
|
|
||||||
|
|
||||||
**Know Foolery** is a comprehensive quiz game application based on the French game "Déconnaissance". The project implements a cross-platform solution with web, mobile (iOS/Android), and desktop applications, featuring secure authentication, microservices architecture, and comprehensive observability.
|
|
||||||
|
|
||||||
## Technology Stack
|
|
||||||
|
|
||||||
- **Backend**: Go with Fiber framework, microservices architecture
|
|
||||||
- **Database**: PostgreSQL (production), SQLite (development)
|
|
||||||
- **ORM**: Ent for type-safe database operations
|
|
||||||
- **Cache**: Redis for session management and caching
|
|
||||||
- **Authentication**: Self-hosted Zitadel (OAuth 2.0/OIDC)
|
|
||||||
- **Frontend**: React (web), React Native (mobile), Wails (desktop)
|
|
||||||
- **UI Framework**: Gluestack UI for cross-platform consistency
|
|
||||||
- **Styling**: NativeWind/Tailwind CSS
|
|
||||||
- **Monitoring**: Prometheus, Grafana, Jaeger
|
|
||||||
- **Containerization**: Docker with Docker Compose
|
|
||||||
|
|
||||||
## Implementation Phases
|
|
||||||
|
|
||||||
### Phase 0: Documentation & Planning ✅ COMPLETED
|
|
||||||
- [x] Create requirements.md with complete application requirements
|
|
||||||
- [x] Create CLAUDE.md project guidance file
|
|
||||||
- [x] Document game mechanics and scoring system
|
|
||||||
- [x] Document technical requirements and architecture decisions
|
|
||||||
- [x] Create architecture documentation with Zitadel integration
|
|
||||||
- [x] Document development guidelines and coding standards
|
|
||||||
- [x] Document observability strategy
|
|
||||||
- [x] Document security requirements
|
|
||||||
- [x] Document cross-platform UI strategy with Gluestack UI
|
|
||||||
|
|
||||||
**Completion Date**: Phase 0 completed successfully with comprehensive documentation covering all aspects of the project.
|
|
||||||
|
|
||||||
### Phase 1: Project Setup & Core Security Infrastructure
|
|
||||||
- [ ] Initialize Go project structure with microservices architecture
|
|
||||||
- [ ] Set up Ent schema definitions for core entities (User, Quiz, Question, etc.)
|
|
||||||
- [ ] Create ZitadelRepository interface for external auth integration
|
|
||||||
- [ ] Set up development environment with Docker Compose
|
|
||||||
- [ ] Initialize Gluestack UI setup with theme configuration
|
|
||||||
- [ ] Implement core security middleware and input validation
|
|
||||||
- [ ] Set up Prometheus metrics collection foundation
|
|
||||||
- [ ] Create basic CI/CD pipeline structure
|
|
||||||
|
|
||||||
### Phase 2: Authentication & User Management
|
|
||||||
- [ ] Implement Zitadel integration with repository pattern
|
|
||||||
- [ ] Create JWT validation middleware with circuit breaker
|
|
||||||
- [ ] Build user registration and profile management
|
|
||||||
- [ ] Implement role-based access control (player/admin)
|
|
||||||
- [ ] Add MFA requirements for admin access
|
|
||||||
- [ ] Create secure token storage for each platform
|
|
||||||
- [ ] Implement comprehensive authentication testing
|
|
||||||
|
|
||||||
### Phase 3: Core Game Engine
|
|
||||||
- [ ] Implement quiz engine with theme and difficulty support
|
|
||||||
- [ ] Create question management system with validation
|
|
||||||
- [ ] Build scoring system with anti-cheating measures
|
|
||||||
- [ ] Implement session management (30-minute time limits)
|
|
||||||
- [ ] Add hint system with progressive revelation
|
|
||||||
- [ ] Create leaderboard functionality
|
|
||||||
- [ ] Implement comprehensive game testing
|
|
||||||
|
|
||||||
### Phase 4: Cross-Platform Frontend
|
|
||||||
- [ ] Build React web application with Gluestack UI
|
|
||||||
- [ ] Create React Native mobile applications
|
|
||||||
- [ ] Develop Wails desktop application
|
|
||||||
- [ ] Implement shared authentication flows
|
|
||||||
- [ ] Create responsive game interface components
|
|
||||||
- [ ] Add platform-specific optimizations
|
|
||||||
- [ ] Implement comprehensive frontend testing
|
|
||||||
|
|
||||||
### Phase 5: Admin Panel & Content Management
|
|
||||||
- [ ] Build secure admin dashboard
|
|
||||||
- [ ] Create question management interface
|
|
||||||
- [ ] Implement user administration tools
|
|
||||||
- [ ] Add analytics and reporting features
|
|
||||||
- [ ] Create content import/export functionality
|
|
||||||
- [ ] Implement admin-specific security measures
|
|
||||||
- [ ] Add comprehensive admin testing
|
|
||||||
|
|
||||||
### Phase 6: Performance & Optimization
|
|
||||||
- [ ] Implement Redis caching strategy
|
|
||||||
- [ ] Add database query optimization
|
|
||||||
- [ ] Create CDN integration for assets
|
|
||||||
- [ ] Implement API rate limiting
|
|
||||||
- [ ] Add frontend performance optimization
|
|
||||||
- [ ] Create load testing and benchmarks
|
|
||||||
|
|
||||||
### Phase 7: Monitoring & Observability
|
|
||||||
- [ ] Complete Prometheus metrics implementation
|
|
||||||
- [ ] Set up Grafana dashboards
|
|
||||||
- [ ] Implement distributed tracing with Jaeger
|
|
||||||
- [ ] Add comprehensive logging strategy
|
|
||||||
- [ ] Create alerting and notification system
|
|
||||||
- [ ] Implement health checks and monitoring
|
|
||||||
|
|
||||||
### Phase 8: Security Hardening
|
|
||||||
- [ ] Conduct comprehensive security audit
|
|
||||||
- [ ] Implement advanced anti-cheating measures
|
|
||||||
- [ ] Add security monitoring and incident response
|
|
||||||
- [ ] Create backup and disaster recovery procedures
|
|
||||||
- [ ] Implement data encryption at rest
|
|
||||||
- [ ] Add comprehensive security testing
|
|
||||||
|
|
||||||
### Phase 9: Production Deployment
|
|
||||||
- [ ] Set up production infrastructure
|
|
||||||
- [ ] Configure CI/CD for production deployment
|
|
||||||
- [ ] Implement monitoring and alerting in production
|
|
||||||
- [ ] Create deployment documentation
|
|
||||||
- [ ] Conduct production readiness review
|
|
||||||
- [ ] Implement production security measures
|
|
||||||
|
|
||||||
### Phase 10: Launch & Post-Launch
|
|
||||||
- [ ] Conduct final testing and quality assurance
|
|
||||||
- [ ] Deploy to production environment
|
|
||||||
- [ ] Monitor launch metrics and performance
|
|
||||||
- [ ] Address any post-launch issues
|
|
||||||
- [ ] Gather user feedback and analytics
|
|
||||||
- [ ] Plan future feature development
|
|
||||||
|
|
||||||
## Key Architectural Decisions
|
|
||||||
|
|
||||||
1. **Repository Pattern**: Used only for external API integrations (Zitadel), direct Ent client usage for database operations
|
|
||||||
2. **Security First**: Critical vulnerabilities addressed in early phases (1-3), enhancements in Phase 8
|
|
||||||
3. **Cross-Platform UI**: Gluestack UI for consistent design across web, mobile, and desktop
|
|
||||||
4. **Microservices**: Go with Fiber framework for high-performance, maintainable services
|
|
||||||
5. **Self-Hosted Auth**: Zitadel for complete control over authentication and user data
|
|
||||||
6. **Comprehensive Testing**: Unit and integration testing after each implementation phase
|
|
||||||
|
|
||||||
## Current Status
|
|
||||||
|
|
||||||
**Phase 0 Complete**: All documentation has been created and is ready for implementation. The project has comprehensive documentation covering:
|
|
||||||
|
|
||||||
- Complete requirements and specifications
|
|
||||||
- Technical architecture with microservices design
|
|
||||||
- Security requirements and implementation strategy
|
|
||||||
- Cross-platform UI strategy with Gluestack UI
|
|
||||||
- Development guidelines and coding standards
|
|
||||||
- Observability and monitoring strategy
|
|
||||||
- Game mechanics and anti-cheating measures
|
|
||||||
- Zitadel authentication integration
|
|
||||||
|
|
||||||
**Next Steps**: Ready to begin Phase 1 (Project Setup & Core Security Infrastructure) upon approval to proceed with implementation.
|
|
||||||
|
|
||||||
## Files Created
|
|
||||||
|
|
||||||
1. `/requirements.md` - Complete project requirements and specifications
|
|
||||||
2. `/CLAUDE.md` - Project guidance for future Claude Code sessions
|
|
||||||
3. `/docs/game-mechanics.md` - Game flow, scoring, and anti-cheating measures
|
|
||||||
4. `/docs/technical-architecture.md` - System architecture and service design
|
|
||||||
5. `/docs/zitadel-integration.md` - Authentication architecture and implementation
|
|
||||||
6. `/docs/development-guidelines.md` - Coding standards and patterns
|
|
||||||
7. `/docs/observability-strategy.md` - Monitoring and metrics strategy
|
|
||||||
8. `/docs/security-requirements.md` - Security strategy and requirements
|
|
||||||
9. `/docs/gluestack-ui-strategy.md` - Cross-platform UI implementation strategy
|
|
||||||
|
|
||||||
All documentation includes comprehensive code examples, implementation details, and best practices for building a secure, scalable quiz game application.
|
|
||||||
@ -1,5 +0,0 @@
|
|||||||
module knowfoolery
|
|
||||||
|
|
||||||
go 1.25.0
|
|
||||||
|
|
||||||
require github.com/stretchr/testify v1.10.0 // indirect
|
|
||||||
Loading…
Reference in New Issue