fixed things

.claude/agents/devops.md

@@ -11,6 +11,8 @@ You are the **DevOps Engineer** responsible for infrastructure, deployment, and
 - Configure Docker containerization for Job Forge prototype
 - Handle server deployment and resource optimization
 - Manage AI API key security and configuration
+- **MANDATORY**: All Docker files must be stored in `docker/` folder
+- **MANDATORY**: Document deployment issues and solutions in `docs/lessons-learned/`
 
 ### 2. Deployment Pipeline for Prototyping
 - Simple deployment pipeline for server hosting

.claude/agents/full-stack-developer.md

@@ -18,6 +18,8 @@ You are the **Senior Full-Stack Developer** responsible for implementing both Fa
 - Connect frontend to FastAPI backend APIs
 - Create intuitive job application management interfaces
 - Optimize for performance and user experience
+- **MANDATORY**: Follow clean project structure (only source code in `src/`)
+- **MANDATORY**: Document any issues encountered in `docs/lessons-learned/`
 
 ## Technology Stack - Job Forge
 

.claude/agents/qa.md

@@ -18,6 +18,8 @@ You are the **QA Engineer** responsible for ensuring high-quality software deliv
 - Database RLS policy testing
 - AI service integration testing with mocks
 - Performance testing for concurrent users
+- **MANDATORY**: All test files must be in `tests/` directory only
+- **MANDATORY**: Document test failures and solutions in `docs/lessons-learned/`
 
 ### 3. Manual Testing & Validation
 - Exploratory testing for job application workflows

.claude/agents/technical-lead.md

@@ -19,12 +19,14 @@ You are the **Technical Lead** responsible for architecture decisions, code qual
 - Review and approve major architectural changes
 - Ensure security best practices for job application data
 
-### 3. Quality Assurance
+### 3. Quality Assurance & Project Structure
 - Python code review standards
 - pytest testing strategy
 - FastAPI performance requirements
 - Multi-tenant security guidelines
 - AI integration documentation standards
+- **MANDATORY**: Enforce clean project structure (only necessary files in root)
+- **MANDATORY**: Document all issues in `docs/lessons-learned/` with solutions
 
 ## Technology Stack - Job Forge
 

.claude/settings_local_json.json

@@ -10,9 +10,15 @@
     "deny": []
   },
   "project": {
-    "name": "SaaS Development Project",
+    "name": "Job Forge Project",
     "type": "web-application",
-    "tech_stack": ["Node.js", "React", "TypeScript", "PostgreSQL"]
+    "tech_stack": [
+      "python3.12",
+      "fastapi",
+      "dash",
+      "mantine",
+      "postgresql"
+    ]
   },
   "team": {
     "main_orchestrator": "CLAUDE.md",
@@ -35,7 +41,11 @@
     "default_agent": "CLAUDE.md"
   },
   "development": {
-    "environments": ["development", "staging", "production"],
+    "environments": [
+      "development",
+      "staging",
+      "production"
+    ],
     "testing_required": true,
     "code_review_required": true
   },

CLAUDE.md

@@ -332,10 +332,70 @@ Your specialized development team is ready to deliver the Job Forge AI-powered j
 
 **Start building your Job Forge prototype!** 🚀
 
-# Documentation Structure
-All project documentation is centralized in the `docs/` folder. See [README.md](README.md) for complete documentation navigation.
+## Project Structure and Organization
+
+### 📁 Clean Project Structure Requirements
+**MANDATORY**: Only necessary files should be stored in the project root folder. All supporting files must be organized into appropriate subdirectories:
+
+```
+job-forge/
+├── src/                    # Source code only
+├── tests/                  # Test files only
+├── docs/                   # All documentation
+├── docker/                 # All Docker-related files
+├── database/               # Database scripts and migrations
+├── .env.example           # Environment template
+├── requirements-*.txt     # Python dependencies
+├── pytest.ini            # Test configuration
+└── README.md              # Main project readme
+```
+
+### 🔧 Docker Files Organization
+All Docker-related files are stored in the `docker/` folder:
+- `docker/docker-compose.yml` - Main orchestration file
+- `docker/Dockerfile.backend` - Backend container definition
+- `docker/Dockerfile.frontend` - Frontend container definition
+
+**Usage**: Run `cd docker && docker compose up -d` to start the environment.
+
+### 📚 Documentation Structure Requirements
+All project documentation is centralized in the `docs/` folder:
+- `docs/lessons-learned/` - **MANDATORY**: All project issues and solutions
+- `docs/api_specification.md` - API documentation
+- `docs/database_design.md` - Database schema and design
+- `docs/development/` - Development guides and standards
+
+### 📝 Lessons Learned Process
+**MANDATORY**: For every issue encountered during development:
+1. Create a new markdown file in `docs/lessons-learned/`
+2. Use format: `###-issue-name.md` (where ### is sequential number)
+3. Include: Issue name, description, error messages, root cause, solution, prevention strategy
+4. Reference the lesson learned in relevant documentation
+
+### 🏗️ Development Environment Setup
+```bash
+# 1. Clone and navigate to project
+git clone <repository>
+cd job-forge
+
+# 2. Set up environment variables
+cp .env.example .env
+# Edit .env with your API keys
+
+# 3. Start development environment
+cd docker
+docker compose up -d
+
+# 4. Access applications
+# Frontend: http://localhost:8501
+# Backend: http://localhost:8000
+# Database: localhost:5432
+```
 
 # Important Instructions
+- **Clean Structure**: Only necessary files in project root
+- **Docker Organization**: All Docker files in `docker/` folder
+- **Lessons Learned**: Document all issues in `docs/lessons-learned/`
 - Focus on Python/FastAPI backend implementation
 - Use Dash + Mantine for frontend components  
 - Prioritize core job application workflows

README.md

@@ -14,11 +14,18 @@
 git clone https://github.com/yourusername/job-forge.git
 cd job-forge
 
-# Start development environment
-docker-compose up -d
+# Set up environment variables
+cp .env.example .env
+# Edit .env with your API keys (Claude, OpenAI, JWT secret)
 
-# Access the application
-open http://localhost:8000
+# Start development environment
+cd docker
+docker compose up -d
+
+# Access the applications
+# Frontend: http://localhost:8501
+# Backend API: http://localhost:8000
+# Database: localhost:5432
 ```
 
 ## 📚 Documentation Navigation

docker/docker-compose.yml

@@ -12,7 +12,7 @@ services:
       - "5432:5432"
     volumes:
       - postgres_data:/var/lib/postgresql/data
-      - ./database/init.sql:/docker-entrypoint-initdb.d/init.sql
+      - ../database/init.sql:/docker-entrypoint-initdb.d/init.sql
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U jobforge_user -d jobforge_mvp"]
       interval: 30s
@@ -21,8 +21,8 @@ services:
 
   backend:
     build:
-      context: .
-      dockerfile: Dockerfile.backend
+      context: ..
+      dockerfile: docker/Dockerfile.backend
     container_name: jobforge_backend
     ports:
       - "8000:8000"
@@ -34,7 +34,7 @@ services:
       - DEBUG=true
       - LOG_LEVEL=INFO
     volumes:
-      - ./src:/app/src
+      - ../src:/app/src
     depends_on:
       postgres:
         condition: service_healthy
@@ -47,15 +47,15 @@ services:
 
   frontend:
     build:
-      context: .
-      dockerfile: Dockerfile.frontend
+      context: ..
+      dockerfile: docker/Dockerfile.frontend
     container_name: jobforge_frontend
     ports:
       - "8501:8501"
     environment:
       - BACKEND_URL=http://backend:8000
     volumes:
-      - ./src/frontend:/app/src/frontend
+      - ../src/frontend:/app/src/frontend
     depends_on:
       backend:
         condition: service_healthy

docs/lessons-learned/001-dependency-version-conflicts.md

@@ -0,0 +1,49 @@
+# Lesson Learned #001: Dependency Version Conflicts
+
+## Issue Name
+Dependency Version Conflicts in Requirements Files
+
+## Date
+2025-08-02
+
+## Description
+During project setup, encountered version conflicts with Python package dependencies:
+- `pytest-dash==2.5.0` - Version did not exist in PyPI (max available: 2.1.2)
+- `python-bcrypt==4.1.2` - Incorrect package name (should be `bcrypt==4.1.2`)
+
+## Error Messages
+```
+ERROR: Could not find a version that satisfies the requirement pytest-dash==2.5.0 
+(from versions: 0.1.0, 0.1.1, 0.1.2, 0.1.3, 0.2.0rc1, 0.2.0rc2, 0.2.0rc3, 1.0.0, 1.0.1, 1.1.0, 2.0.0rc1, 2.0.0rc2, 2.0.0rc3, 2.0.0rc4, 2.0.0rc5, 2.0.0, 2.1.0, 2.1.1, 2.1.2)
+
+ERROR: Could not find a version that satisfies the requirement python-bcrypt==4.1.2 
+(from versions: 0.3.1, 0.3.2)
+```
+
+## Root Cause
+1. Incorrect package versions specified without checking PyPI availability
+2. Wrong package name used for bcrypt library
+
+## Solution Applied
+1. **Updated pytest-dash version**:
+   - Changed from `pytest-dash==2.5.0` to `pytest-dash==2.1.2`
+   - Verified latest available version on PyPI
+
+2. **Fixed bcrypt package name**:
+   - Changed from `python-bcrypt==4.1.2` to `bcrypt==4.1.2`
+   - Used correct package name
+
+## Files Modified
+- `requirements-backend.txt` - Fixed bcrypt package name
+- `requirements-frontend.txt` - Updated pytest-dash version
+
+## Prevention Strategy
+1. Always verify package versions exist on PyPI before adding to requirements
+2. Use `pip search` or check PyPI website for correct package names
+3. Consider using version ranges instead of exact pins for non-critical dependencies
+4. Implement CI/CD checks to validate requirements files
+
+## Impact
+- ✅ All dependencies now install successfully
+- ✅ Project setup process is streamlined
+- ✅ Development environment can be started without version conflicts

docs/lessons-learned/002-project-structure-organization.md

@@ -0,0 +1,77 @@
+# Lesson Learned #002: Project Structure Organization
+
+## Issue Name
+Project Structure Organization and Clean Root Directory
+
+## Date
+2025-08-02
+
+## Description
+Initial project setup had Docker configuration files scattered in the root directory, making the project structure cluttered and harder to navigate. This violated clean project organization principles.
+
+## Root Cause
+- Docker files (Dockerfile.backend, Dockerfile.frontend, docker-compose.yml) were placed in project root
+- No established guidelines for file organization
+- Lack of mandatory documentation for project issues
+
+## Solution Applied
+1. **Created organized folder structure**:
+   ```
+   job-forge/
+   ├── src/                    # Source code only
+   ├── tests/                  # Test files only
+   ├── docs/                   # All documentation
+   ├── docker/                 # All Docker-related files
+   ├── database/               # Database scripts and migrations
+   ├── .env.example           # Environment template
+   ├── requirements-*.txt     # Python dependencies
+   ├── pytest.ini            # Test configuration
+   └── README.md              # Main project readme
+   ```
+
+2. **Moved Docker files to dedicated folder**:
+   - Moved all Docker files to `docker/` directory
+   - Updated docker-compose.yml paths to reference parent directory (`../`)
+   - Updated project documentation to reflect new structure
+
+3. **Created lessons-learned process**:
+   - Created `docs/lessons-learned/` folder
+   - Established mandatory documentation process for all issues
+   - Added sequential numbering system for lesson learned entries
+
+## Files Modified
+- `docker/docker-compose.yml` - Updated paths for new structure
+- `CLAUDE.md` - Added project structure requirements and lessons learned process
+- `.claude/agents/*.md` - Updated all agent files with structure requirements
+- `README.md` - Updated quick start instructions
+
+## New Mandatory Requirements
+1. **Clean Root Directory**: Only essential files in project root
+2. **Docker Organization**: All Docker files in `docker/` folder
+3. **Lessons Learned**: Document every issue in `docs/lessons-learned/`
+4. **Sequential Documentation**: Use numbered format (###-issue-name.md)
+
+## Prevention Strategy
+1. Establish clear folder structure guidelines in project documentation
+2. Add project structure validation to CI/CD if implemented
+3. Regular project structure reviews during development
+4. Mandatory issue documentation process for all team members
+
+## Usage Instructions
+```bash
+# Start development environment from docker folder
+cd docker
+docker compose up -d
+
+# Access applications
+# Frontend: http://localhost:8501
+# Backend: http://localhost:8000
+# Database: localhost:5432
+```
+
+## Impact
+- ✅ Clean, organized project structure
+- ✅ Easier navigation and maintenance
+- ✅ Established process for documenting project issues
+- ✅ Better adherence to software engineering best practices
+- ✅ Updated all team documentation and agent instructions

requirements-backend.txt

@@ -12,7 +12,7 @@ psycopg2-binary==2.9.9
 # Authentication & Security
 python-jose[cryptography]==3.3.0
 passlib[bcrypt]==1.7.4
-python-bcrypt==4.1.2
+bcrypt==4.1.2
 
 # AI Services
 anthropic==0.21.3

requirements-frontend.txt

@@ -20,6 +20,6 @@ structlog==24.1.0
 
 # Development
 pytest==8.0.2
-pytest-dash==2.5.0
+pytest-dash==2.1.2
 black==24.2.0
 isort==5.13.2