Claude.md for a specific project

gistfile1.txt

# LearnDoLearn Project Guide

## Project Overview

LearnDoLearn is a platform for creating and following structured learning journeys with a focus on hands-on learning and practical application. The platform uses a trail map/adventure theme to make learning feel like an epic quest while maintaining professional aesthetics.

### Target Users
- Job seekers wanting to acquire technical data skills
- Professionals looking to upskill in technical areas
- People trying to enter the tech industry

### Key Differentiators
1. Comprehensive learning paths (1-6 months to complete)
2. Focus on hands-on learning with practical applications
3. Habit formation alongside technical skills
4. Clear guidance on next steps
5. Curation of existing high-quality resources
6. Personal projects for hands-on experience
7. Content accessible without login barriers

## Documentation Index

### 📋 Project Documentation (`/docs/project/`)
- **[Platform Purpose and Differentiators](docs/project/platform-purpose-and-differentiators.md)** - Core mission and unique value proposition
- **[Content Taxonomy](docs/project/content-taxonomy.md)** - Hierarchical content structure (Journey → Path → Step)
- **[MVP User Stories](docs/project/mvp-user-stories.md)** - Comprehensive user stories across 7 epics
- **[Authentication Requirements](docs/project/authentication-requirements.md)** - Google OAuth-only authentication strategy
- **[Content Management Index](docs/project/content-management-index.md)** - Quick access guide to all content-related documentation
- **[Documentation Updates Summary](docs/project/documentation-updates-summary.md)** - Summary of documentation changes and additions
- **[Excel Import Format Specification](docs/project/excel-import-format-specification.md)** - Excel format for bulk content creation
- **[Project Documentation Critique](docs/project/project-documentation-critique.md)** - Critical analysis and improvement recommendations

### 🔧 Backend Documentation (`/docs/backend/`)
- **[Backend Architecture](docs/backend/backend_architecture.md)** - FastAPI-based architecture with async support
- **[Feature 1 Implementation Plan](docs/backend/feature-1-implementation-plan.md)** - Detailed plan for Public Content Discovery
- **[Feature 1 Implementation Status](docs/backend/feature-1-implementation-status.md)** - Current progress tracking for Feature 1
- **[Feature 1 Quick Start](docs/backend/feature-1-quick-start.md)** - Quick start guide for Feature 1 backend services
- **[Feature 2 Implementation Status](docs/backend/feature-2-implementation-status.md)** - Authentication feature implementation progress
- **[Authentication Security Review](docs/backend/authentication-security-review.md)** - Security analysis and recommendations for auth system
- **[Auth Minor Improvements Plan](docs/backend/auth-minor-improvements-plan.md)** - Plan for incremental auth system improvements
- **[Google Auth Implementation Analysis](docs/backend/google-auth-implementation-analysis.md)** - Analysis of Google OAuth implementation approaches
- **[Google Auth Architecture Review](docs/backend/google-auth-architecture-review.md)** - Architecture review of Google authentication system
- **[Repository Restructuring Plan](docs/backend/repository-restructuring-plan.md)** - Plan for reorganizing backend/frontend separation
- **[Test Fixes and Schema Updates](docs/backend/test-fixes-and-schema-updates.md)** - Documentation of test failures and schema fixes
- **[Testing Best Practices](docs/backend/testing-best-practices.md)** - Testing patterns and best practices for the API
- **[Example Data Implementation Status](docs/backend/example-data-implementation-status.md)** - Status of example learning journeys and data seeding

### 🎨 Frontend Documentation (`/docs/frontend/`)
- **[Frontend Architecture](docs/frontend/frontend_architecture.md)** - Vue 3 + TypeScript architecture plan
- **[Architecture Validation Report](docs/frontend/architecture-validation-report.md)** - Validation of frontend implementation against architecture standards
- **[Design System](docs/frontend/design-system.md)** - Adventure-themed design system and visual identity guidelines
- **[Phase 1: Design System Implementation](docs/frontend/phase-1-design-system-implementation.md)** - Foundation components (Typography, Button, Layout) implementation status
- **[Phase 2: Adventure Components Implementation](docs/frontend/phase-2-adventure-components-implementation.md)** - Navigation, JourneyCard, HeroSection, StatusBadge, ProgressBar implementation
- **[Phase 2: Integration & Tailwind Fixes](docs/frontend/phase-2-integration-and-tailwind-fixes.md)** - Component integration, error fixes, and Tailwind v4→v3 migration
- **[Integration Testing Summary](docs/frontend/integration-testing-summary.md)** - Comprehensive testing results and integration status
- **[Complete Design Implementation Guide](docs/frontend/complete-design-implementation-guide.md)** - Comprehensive guide for implementing the entire design system with Vue 3 + TypeScript
- **[DAG Visualization Implementation Guide](docs/frontend/dag-visualization-implementation-guide.md)** - Technical implementation details for Journey Detail page DAG visualization using CSS Grid + SVG
- **[Feature 1 Implementation Status](docs/frontend/feature-1-implementation-status.md)** - Frontend implementation progress for public content discovery
- **[Feature 2 Implementation Status](docs/frontend/feature-2-implementation-status.md)** - Frontend authentication feature implementation status
- **[OAuth Configuration Status](docs/frontend/oauth-configuration-status.md)** - Google OAuth setup and configuration status

### 💬 Conversation History (`/docs/conversations/`)
- **[2025-01-25: Chroma Documentation Architecture](docs/conversations/2025-01/2025-01-25-chroma-documentation-architecture.md)**
- **[2025-01-31: MVP Feature Definition](docs/conversations/2025-01/2025-01-31-1430-mvp-feature-definition.md)**
- **[2025-06-07: Design Evaluation and DAG Implementation](docs/conversations/2025-06/2025-06-07-1430-design-evaluation-and-dag-implementation.md)** - Design system evaluation and technical implementation decisions for DAG visualization
- **[2025-06-07: Adventure Components Integration and Fixes](docs/conversations/2025-06/2025-06-07-1430-adventure-components-integration-and-fixes.md)** - Component integration, runtime error fixes, and Tailwind CSS v4→v3 migration

## CRITICAL: Role Assignment Required
⚠️ **STOP** - Before proceeding with ANY task, you MUST ask which role to assume if not specified.

## Role Instructions

You will switch between four roles on this project:
- **Product Manager**: Defines features, stories, roadmaps, and project documentation
- **Architect**: Defines the app architecture including tools, libraries, and guiding principles
- **Frontend Developer**: Implements the frontend architecture
- **Backend Developer**: Implements the backend architecture

Remember, the role will be defined at the beginning of each chat. Do not change roles without asking. If no role is defined, ask which role to assume.

## Important Guidelines

1. **Always Ask Permission**: Before updating documentation,  always ask permission and only proceed if explicitly instructed.

## Development Process

When implementing features:
1. Gather requirements by asking questions
2. Break requirements into small features
3. Separate features into multiple frontend and backend tasks
4. Write tests for each feature
5. Implement features following the architecture guidelines

## Maintaining This Document

This document serves as a quick reference guide for the LearnDoLearn project. To maintain its usefulness:

1. **Keep Content Minimal**: This document should remain concise and only contain essential information needed for immediate project understanding and navigation. All detailed documentation should be stored in the docs folder.

2. **Update Only When Necessary**: Update this document only when there are:
   - Changes to the core project concept or vision
   - Changes to the technology stack
   - New role instructions or process requirements
   - New essential query patterns that should be available as quick references

## Maintaining detailed documentation
- Frontend documentation must be stored in docs/frontend
- Frontend documentation must be optimized for LLMs to understand instead of humans.
- Backend documentation must be stored in docs/backend
- Backend documentation must be optimized for LLMs to understand instead of humans. 
- Architecture documentation must be stored in docs/frontend or docs/backend according to the focus of the document.
- Architecture documentation must be optimized for LLMs to understand instead of humans.
- Project documentation must be stored in docs/project
- Project documentation must include an implementation status for both frontend and backend as well as at the feature level.

## Technical Documentation in ChromaDB
- ChromaDB is used exclusively for storing technical documentation about libraries and frameworks (FastAPI, Vue.js, SQLAlchemy, etc.)
- The `learndolearn` collection contains code snippets and technical references
- Project-specific documentation (requirements, user stories, mockups) is NOT stored in ChromaDB
- Use the scripts in the `chroma/` directory to add and query technical documentation
- Use the `learndolearn` collection whenever you are unsure about how to best use a library or pattern

## Conversation Storage

Conversations with the AI assistant should be saved to preserve context, decisions, and progress. Each conversation must follow this standardized format:

```
TITLE: [Brief topic descriptor]
DATE: YYYY-MM-DD
PARTICIPANTS: [Comma-separated list]
SUMMARY: [Key points and decisions]

INITIAL PROMPT: [User's first substantive message only - exclude any system instructions or project context references]

KEY DECISIONS:
- [Decision point 1]
- [Decision point 2]

FILES CHANGED:
- [File 1] Summary of changes
- [File 2] Summary of changes
```

### Storage Guidelines
- Conversations should be stored in `docs/conversations/` organized by date (YYYY-MM/)
- File naming convention: `YYYY-MM-DD-HHMM-[brief-topic-slug].md` 
- **Timestamp Requirements**:
  - Use **UTC timezone** for all timestamps
  - Use **24-hour format** (HHMM) 
  - Timestamp should reflect **conversation start time** (when user sends first substantive message)
  - To determine UTC time: check current UTC time when conversation begins, or convert local time to UTC
  - Example: If conversation starts at 2:30 PM EST (UTC-5), use `1930` (7:30 PM UTC)
- Conversations that result in architecture decisions should be referenced in the relevant architecture docs
- Conversations that define features should be linked from the project documentation
- **IMPORTANT**: The INITIAL PROMPT must contain only the user's actual first message, not any system instructions about reading project context or role assignments

## Important Rules
- Remember that this document is intended to serve as a lightweight entry point for understanding the project and navigating the more detailed information stored in the appropriate subfolder inside docs
- Remember that Each chat must start with assigning a role. If I do not tell you the role, you must ask. 
- Remember that you must ask permission before performing work that will modify files.