CLAUDE.md

1# CLAUDE.md - Course Creator Platform Documentation
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5**Version**: 3.3.1 - Login Redirect Fixes & Authentication Enhancement
6**Last Updated**: 2025-10-08
7 
8---
9 
10## 🚀 MANDATORY SESSION START PROTOCOL
11 
12**AT THE START OF EVERY SESSION, CLAUDE CODE MUST:**
13 
14### Step 1: Load Core Methodology (30 seconds)
15```bash
16# Check user preferences (CRITICAL - DO THIS FIRST)
17python3 .claude/query_memory.py search "Agile"
18python3 .claude/query_memory.py search "TDD"
19python3 .claude/query_memory.py search "parallel"
20 
21# Review recent context
22python3 .claude/query_memory.py list 20
23```
24 
25### Step 2: Internalize Methodology (No user reminder needed)
26- ✅ User ALWAYS wants Agile + Kanban boards (automatic)
27- ✅ User ALWAYS wants TDD - tests BEFORE code (automatic)
28- ✅ User ALWAYS wants TodoWrite tracking (automatic)
29- ✅ User NEVER wants to be reminded of these preferences
30- ✅ For complex tasks: Use Parallel Agent Development System (PADS)
31 
32### Step 3: Reference Self-Improvement Framework
33- **Read**: `.claude/CLAUDE_SELF_IMPROVEMENT_PLAN.md` for behavioral guidelines
34- **Read**: `.claude/PARALLEL_AGENT_DEVELOPMENT_SYSTEM.md` for parallel workflows
35- **Templates**: `.claude/templates/` for TDD, Kanban, session checklists
36 
37### Step 4: Confirm Readiness
38Silently confirm understanding of:
39- Memory-first workflow
40- TDD approach (Red-Green-Refactor)
41- Parallel agent development for efficiency
42- TodoWrite for task tracking
43- Tentative language (no false claims)
44 
45**THESE ARE NOW DEFAULT BEHAVIOR - NOT OPTIONAL**
46 
47---
48 
49## 📁 Documentation Structure
50 
51This documentation is organized into logical sections within the `claude.md/` subdirectory:
52 
53### Core Requirements & Standards
54- **[Critical Requirements](claude.md/01-critical-requirements.md)** - Absolute imports, exception handling, file editing efficiency
55- **[Documentation Standards](claude.md/02-documentation-standards.md)** - Comprehensive code documentation requirements
56- **[Memory System](claude.md/03-memory-system.md)** - Mandatory persistent memory system usage
57 
58### Version History & Features
59- **[Version History](claude.md/04-version-history.md)** - Platform evolution and feature updates
60- **[Architecture Overview](claude.md/05-architecture.md)** - Microservices structure and dependencies
61- **[Key Systems](claude.md/06-key-systems.md)** - Quiz management, feedback, RBAC, RAG, lab containers
62 
63### Development & Operations
64- **[Development Commands](claude.md/07-development-commands.md)** - Platform management, testing, database operations
65- **[Testing Strategy](claude.md/08-testing-strategy.md)** - Comprehensive testing framework and requirements
66- **[Quality Assurance](claude.md/09-quality-assurance.md)** - Code validation, CI/CD pipeline, compliance verification
67- **[Troubleshooting](claude.md/10-troubleshooting.md)** - Common issues, debugging, problem-solving methodology
68 
69## 🚨 CRITICAL BEHAVIORAL REQUIREMENTS FOR CLAUDE CODE
70 
71### 1. MANDATORY COMPREHENSIVE E2E SELENIUM TESTING - ALL ROLES (v3.2.2)
72**HIGHEST PRIORITY - APPLIES TO ALL CODE CHANGES**
73 
74- **MANDATORY**: Subagents MUST perform Selenium E2E tests on **EVERY feature and pathway for ALL user roles**
75- **NO EXCEPTIONS**: All user journeys for ALL 4 roles must have complete E2E test coverage
76- **TARGET**: 90%+ E2E coverage across 14 major feature areas and ALL roles (currently ~45-60%)
77- **CRITICAL REQUIREMENT**: Test ALL roles, not just students!
78 
79**User Roles Requiring Complete Coverage (4 authenticated + 1 unauthenticated):**
801. **Site Admin** - Platform administration, all organizations, system configuration
812. **Organization Admin** - Member management, organization settings, tracks, compliance
823. **Instructor** - Course creation, content generation, student management, analytics
834. **Student** - Learning workflows, assessments, labs, progress tracking
845. **Anonymous/Guest** - Public pages, registration, course browsing (unauthenticated)
85 
86**Comprehensive Test Plan:** `/home/bbrelin/course-creator/tests/COMPREHENSIVE_E2E_TEST_PLAN.md`
87 
88**Priority 0 Tests (Must Implement First) - ALL ROLES:**
891. Complete Student Learning Journey (Login → Learn → Quiz → Lab → Certificate)
902. Complete Instructor Workflow (Create Course → Generate Content → Manage Students → Analytics)
913. Complete Organization Admin Workflow (Manage Members → Configure Org → Tracks → Reports)
924. Complete Site Admin Workflow (Platform Admin → Monitor System → Manage All Orgs)
935. Anonymous/Guest Workflows (Browse → Register → Password Reset)
946. RAG AI Assistant Workflow (ALL roles can interact with AI)
957. Content Generation Pipeline (Instructor role)
96 
97**Quick Test Command:**
98```bash
99# Run Priority 0 tests for ALL roles
100pytest tests/e2e/critical_user_journeys/ -v
101 
102# Run specific role tests
103pytest tests/e2e/critical_user_journeys/test_student_complete_journey.py -v
104pytest tests/e2e/critical_user_journeys/test_instructor_complete_journey.py -v
105pytest tests/e2e/critical_user_journeys/test_org_admin_complete_journey.py -v
106pytest tests/e2e/critical_user_journeys/test_site_admin_complete_journey.py -v
107pytest tests/e2e/critical_user_journeys/test_guest_complete_journey.py -v
108```
109 
110### 2. MANDATORY DOCKER INFRASTRUCTURE TESTING (v3.2.2)
111**SECOND HIGHEST PRIORITY - APPLIES TO ALL CODE CHANGES**
112 
113- **BEFORE** any PR or commit: ALL Docker containers MUST be healthy
114- **MANDATORY** GitHub Actions workflow: `docker-infrastructure-test` must pass
115- **NO EXCEPTIONS**: Every code change requires Docker health verification
116- **ALL 16 SERVICES** must pass health checks with HTTPS enabled
117- **VERIFICATION REQUIRED**: Run `./scripts/app-control.sh status` and confirm all green checkmarks
118 
119**Quick Verification Command:**
120```bash
121# THIS MUST PASS BEFORE ANY PR
122./scripts/app-control.sh status 2>&1 | grep "✅"
123# Expected: 16 services showing "✅ Healthy"
124```
125 
126### 3. NO FALSE SUCCESS CLAIMS
127- **NEVER** claim a task is "completed" or "successful" unless you have PROVEN it works through actual testing
128- **NEVER** say "✅" or mark anything as working without concrete evidence
129- **NEVER** use phrases like "successfully completed", "working correctly", "fixed", "healthy" without verification
130 
131### 4. MANDATORY VERIFICATION REQUIREMENTS
132- Before claiming ANY task completion, you MUST provide concrete evidence:
133  - Service responding to HTTP requests with 200 status
134  - Actual command output showing success
135  - Container running with "Up (healthy)" status
136  - Real test results, not assumptions
137  - **Docker infrastructure tests passing** (see requirement #1)
138 
139### 5. MANDATORY MEMORY TOOL USAGE - ALWAYS FIRST, EVERY TASK
140 
141**CRITICAL RULE: MEMORY SEARCH IS THE FIRST ACTION FOR EVERY TASK**
142 
143Before doing ANYTHING - before reading files, before writing code, before running commands - you MUST:
144 
1451. **Search memory for task-relevant facts** (keywords: technology, feature, component)
1462. **Search memory for constraints** (keywords: HTTPS, requirements, architecture)
1473. **Review recent context** (`list 20`)
148 
149**Memory Tool Commands:**
150```bash
151# ALWAYS START WITH THESE - NO EXCEPTIONS
152python3 .claude/query_memory.py search "relevant_keyword"
153python3 .claude/query_memory.py search "constraints"
154python3 .claude/query_memory.py list 20
155 
156# Add new facts AFTER discoveries
157python3 .claude/query_memory.py add "<fact_content>" "<category>" "<importance>"
158```
159 
160**Why This Matters:**
161- Prevents repeating mistakes (like using HTTP instead of HTTPS)
162- Ensures critical requirements aren't forgotten
163- Maintains consistency with user preferences
164- Avoids redundant work
165 
166**Mandatory Memory Workflow:**
1671. **BEFORE** making any technical decision → Search memory for relevant facts
1682. **DURING** investigation → Document findings as you discover them
1693. **AFTER** fixing bugs → Add facts about root cause and solution
1704. **NEVER** assume you know something → Verify it exists in memory first
171 
172**Example Workflow:**
173```bash
174# User says: "The platform uses HTTPS only"
175# Step 1: Search memory to verify
176python3 .claude/query_memory.py search "HTTPS"
177# Found: ID 300 confirms HTTPS-only requirement
178 
179# Step 2: Work on the task using this fact
180 
181# Step 3: Add new discovery
182python3 .claude/query_memory.py add "Service endpoint discovered: /users/me (not /api/v1/users/me)" "api-endpoints" "critical"
183```
184 
185### 4. MEMORY AND STATE TRACKING
186- **ALWAYS** maintain accurate state of what has been attempted vs. what actually works
187- If something failed before, acknowledge it failed and explain what's different this time
188- Keep track of which services/components are genuinely working vs. still broken
189 
190### 5. TRUTHFUL STATUS REPORTING
191When reporting status, use only these categories:
192- **WORKING**: Verified with evidence (show the evidence)
193- **ATTEMPTED**: Tried but not verified to work
194- **BROKEN**: Confirmed not working
195- **UNKNOWN**: Not yet tested
196 
197### 6. PROBLEM ACKNOWLEDGMENT
198- If you encounter the same error repeatedly, STOP and acknowledge the pattern
199- Don't keep trying the same approach that already failed
200- Ask for guidance when stuck in loops
201 
202### 7. NO ASSUMPTION-BASED CLAIMS
203- Don't claim something works because "the code looks right"
204- Don't assume Docker containers work because they built successfully
205- Verify actual functionality, not just absence of build errors
206 
207### 8. SYSTEMATIC VERIFICATION PROTOCOL
208**Before claiming ANY fix works, you MUST:**
209- **Test the exact failing case** - Copy/paste the exact error scenario and reproduce it
210- **Test in the actual environment** - Not just isolated unit tests, but in the real deployment context
211- **Provide evidence** - Show the before/after comparison with actual output
212- **Wait for user confirmation** - Never declare success, only "attempted fix - please verify"
213 
214### 9. LANGUAGE RESTRICTIONS
215**FORBIDDEN phrases (never use these without concrete proof):**
216- ✅ "PROVEN: [anything] is working"
217- ✅ "The error should now be resolved"
218- ✅ "Pattern/code compiles successfully!"
219- ✅ "Both fixes are working"
220- ✅ "Successfully completed"
221- ✅ "Working correctly"
222 
223**REQUIRED language (always use these instead):**
224- 🔄 "I've made a change that might fix this. Please test it."
225- 🔄 "Here's what I changed and why. Can you verify if it works?"
226- 🔄 "The pattern works in my test, but please confirm in your browser."
227- 🔄 "Attempted fix deployed - needs user verification"
228 
229### 10. ROOT CAUSE ANALYSIS REQUIREMENT
230**When debugging, you MUST:**
231- **Understand the problem** (not just pattern-match visual symptoms)
232- **Research the root cause** (don't guess based on superficial similarities)
233- **Test exact scenario** (reproduce the exact failure first)
234- **Make minimal changes** (one thing at a time)
235- **Document uncertainty** (what you're not sure about)
236 
237### 11. ANTI-PATTERN RECOGNITION
238**Recognize and STOP these harmful patterns:**
239- Visual pattern recognition → quick fix instinct → biased testing
240- "This looks wrong" → make change → assume it's fixed
241- Deployment success → claim functional success
242- Isolated test passes → claim real-world functionality
243- Speed/confidence prioritized over accuracy/verification
244 
245### 12. EPISTEMOLOGICAL HUMILITY
246**Acknowledge the limits of what you can know:**
247- You cannot directly interact with user browsers
248- You cannot see actual user experience
249- Your tests are simulations, not reality
250- Deployment ≠ functionality
251- Code compilation ≠ runtime success
252 
253## 🚨 Critical Code Directives (Always Apply)
254 
255### 1. Python Import Requirements
256**ABSOLUTE IMPORTS ONLY** - Never use relative imports (`from ..`, `from .`) in Python files.
257 
258**SERVICE-SPECIFIC NAMESPACES** - All services use service-specific namespaces to prevent collision:
259 
260**9 Services with Clean Architecture (domain/application/infrastructure layers):**
261- `analytics` → imports from `analytics.domain.*`, `analytics.application.*`, `analytics.infrastructure.*`
262- `content-management` → imports from `content_management.domain.*`, `content_management.application.*`, `content_management.infrastructure.*`
263- `course-generator` → imports from `course_generator.domain.*`, `course_generator.application.*`, `course_generator.infrastructure.*`
264- `course-management` → imports from `course_management.domain.*`, `course_management.application.*`, `course_management.infrastructure.*`
265- `knowledge-graph-service` → imports from `knowledge_graph_service.domain.*`, `knowledge_graph_service.application.*`, `knowledge_graph_service.infrastructure.*`
266- `metadata-service` → imports from `metadata_service.domain.*`, `metadata_service.application.*`, `metadata_service.infrastructure.*`
267- `nlp-preprocessing` → imports from `nlp_preprocessing.domain.*`, `nlp_preprocessing.application.*`, `nlp_preprocessing.infrastructure.*`
268- `organization-management` → imports from `organization_management.domain.*`, `organization_management.application.*`, `organization_management.infrastructure.*`
269- `user-management` → imports from `user_management.domain.*`, `user_management.application.*`, `user_management.infrastructure.*`
270 
271**Directory Structure:**
272```
273services/SERVICE-NAME/
274├── service_name_package/       # ← New namespace directory (underscored)
275│   ├── __init__.py
276│   ├── domain/                 # ← Domain layer under service namespace
277│   │   └── entities/
278│   ├── application/            # ← Application layer under service namespace
279│   │   └── services/
280│   └── infrastructure/         # ← Infrastructure layer under service namespace
281│       └── repositories/
282├── data_access/                # ← Shared DAOs (not in namespace)
283├── api/                        # ← API endpoints (not in namespace)
284└── main.py                     # ← Service entry point
285```
286 
287**Import Examples:**
288```python
289# OLD (namespace collision - DO NOT USE):
290from domain.entities.course import Course
291from application.services.course_service import CourseService
292 
293# NEW (service-specific namespace - USE THIS):
294from course_management.domain.entities.course import Course
295from course_management.application.services.course_service import CourseService
296```
297 
298**Note**: Service directory names use hyphens (`content-management`), but Python package names use underscores (`content_management`).
299 
300### 2. Exception Handling
301**CUSTOM EXCEPTIONS MANDATORY** - Never use generic `except Exception as e` handlers. Use structured custom exceptions with f-strings.
302 
303### 3. Documentation Requirements
304**COMPREHENSIVE DOCUMENTATION** - All code must include multiline string documentation explaining business context and technical rationale.
305 
306### 4. Memory System Usage
307**MANDATORY MEMORY SYSTEM** - Must use the persistent memory system for context continuity across conversations.
308 
309### 5. File Type-Specific Comment Syntax
310- Python: `"""multiline strings"""` 
311- JavaScript: `//` or `/* */`
312- CSS: `/* */`
313- HTML: `<!-- -->`
314- YAML: `#`
315- SQL: `--` or `/* */`
316- Bash: `#`
317 
318## 🏗️ Platform Overview
319 
320The Course Creator Platform is a comprehensive educational technology system with:
321 
322- **9 Microservices** (ports 8000-8010) providing authentication, content generation, lab management, analytics, RBAC, and demo functionality
323- **Multi-IDE Lab Environment** with individual Docker containers for students
324- **Enhanced RBAC System** with multi-tenant organization management and Guest role
325- **RAG-Enhanced AI** for progressive learning and content generation
326- **Demo Service** with realistic data generation for platform demonstration (port 8010)
327- **Guest Session Privacy Compliance** with GDPR/CCPA/PIPEDA-compliant PostgreSQL storage and privacy APIs
328- **Enhanced AI Chatbot** with NLP, RAG, knowledge graph integration, and personalized onboarding
329- **Comprehensive Testing** with 102 RBAC tests achieving 100% success rate plus 101+ demo service tests
330- **Advanced Password Management** with secure admin account creation and self-service password changes
331- **Enhanced UI/UX** with keyboard navigation, accessibility features, and responsive design
332 
333## 📖 How to Read This Documentation
334 
335When Claude Code needs to reference this documentation:
336 
3371. **Start here** - Read this root file for overview and critical directives
3382. **Navigate to specific sections** - Use the links above to access detailed information
3393. **Follow cross-references** - Related sections reference each other for comprehensive understanding
340 
341## 🔄 Quick Navigation
342 
343For immediate needs:
344- **Development Setup**: See [Development Commands](claude.md/07-development-commands.md)
345- **Troubleshooting**: See [Troubleshooting](claude.md/10-troubleshooting.md)
346- **Architecture Questions**: See [Architecture Overview](claude.md/05-architecture.md)
347- **Testing Issues**: See [Testing Strategy](claude.md/08-testing-strategy.md)
348- **Privacy Compliance**: See [Guest Session Privacy Compliance](docs/GUEST_SESSION_PRIVACY_COMPLIANCE.md)
349- **Privacy API**: See [Privacy API Documentation](docs/PRIVACY_API_DOCUMENTATION.md)
350 
351---
352 
353**COMPLIANCE REQUIREMENT**: All code must adhere to the critical directives listed above and the detailed requirements in the subdirectory files.