From c9f25ea1490a87c7c0b29710a352d9d344698f85 Mon Sep 17 00:00:00 2001 From: l3ocho Date: Sat, 2 Aug 2025 16:20:23 -0400 Subject: [PATCH] fixed things --- .../{simplified_devops.md => devops.md} | 2 + ...k_developer.md => full-stack-developer.md} | 2 + .claude/agents/{simplified_qa.md => qa.md} | 2 + ...ed_technical_lead.md => technical-lead.md} | 4 +- .claude/settings_local_json.json | 18 ++++- .../{api_docs_template.md => api-docs.md} | 0 .../{deployment_template.md => deployment.md} | 0 .../{testing_template.md => testing.md} | 0 CLAUDE.md | 64 ++++++++++++++- README.md | 15 +++- .../Dockerfile.backend | 0 .../Dockerfile.frontend | 0 .../docker-compose.yml | 14 ++-- .../001-dependency-version-conflicts.md | 49 ++++++++++++ .../002-project-structure-organization.md | 77 +++++++++++++++++++ requirements-backend.txt | 2 +- requirements-frontend.txt | 2 +- 17 files changed, 231 insertions(+), 20 deletions(-) rename .claude/agents/{simplified_devops.md => devops.md} (99%) rename .claude/agents/{fullstack_developer.md => full-stack-developer.md} (99%) rename .claude/agents/{simplified_qa.md => qa.md} (99%) rename .claude/agents/{simplified_technical_lead.md => technical-lead.md} (97%) rename .claude/templates/{api_docs_template.md => api-docs.md} (100%) rename .claude/templates/{deployment_template.md => deployment.md} (100%) rename .claude/templates/{testing_template.md => testing.md} (100%) rename Dockerfile.backend => docker/Dockerfile.backend (100%) rename Dockerfile.frontend => docker/Dockerfile.frontend (100%) rename docker-compose.yml => docker/docker-compose.yml (84%) create mode 100644 docs/lessons-learned/001-dependency-version-conflicts.md create mode 100644 docs/lessons-learned/002-project-structure-organization.md diff --git a/.claude/agents/simplified_devops.md b/.claude/agents/devops.md similarity index 99% rename from .claude/agents/simplified_devops.md rename to .claude/agents/devops.md index 4edc35f..bb39b7d 100644 --- a/.claude/agents/simplified_devops.md +++ b/.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 diff --git a/.claude/agents/fullstack_developer.md b/.claude/agents/full-stack-developer.md similarity index 99% rename from .claude/agents/fullstack_developer.md rename to .claude/agents/full-stack-developer.md index 9d0b1a9..1ff9c7a 100644 --- a/.claude/agents/fullstack_developer.md +++ b/.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 diff --git a/.claude/agents/simplified_qa.md b/.claude/agents/qa.md similarity index 99% rename from .claude/agents/simplified_qa.md rename to .claude/agents/qa.md index 2c44020..9bdbc02 100644 --- a/.claude/agents/simplified_qa.md +++ b/.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 diff --git a/.claude/agents/simplified_technical_lead.md b/.claude/agents/technical-lead.md similarity index 97% rename from .claude/agents/simplified_technical_lead.md rename to .claude/agents/technical-lead.md index abe6af7..45c8e49 100644 --- a/.claude/agents/simplified_technical_lead.md +++ b/.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 diff --git a/.claude/settings_local_json.json b/.claude/settings_local_json.json index 448dfe9..d4738ec 100644 --- a/.claude/settings_local_json.json +++ b/.claude/settings_local_json.json @@ -10,15 +10,21 @@ "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", "specialist_agents": [ "agents/technical-lead.md", - "agents/full-stack-developer.md", + "agents/full-stack-developer.md", "agents/devops.md", "agents/qa.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 }, diff --git a/.claude/templates/api_docs_template.md b/.claude/templates/api-docs.md similarity index 100% rename from .claude/templates/api_docs_template.md rename to .claude/templates/api-docs.md diff --git a/.claude/templates/deployment_template.md b/.claude/templates/deployment.md similarity index 100% rename from .claude/templates/deployment_template.md rename to .claude/templates/deployment.md diff --git a/.claude/templates/testing_template.md b/.claude/templates/testing.md similarity index 100% rename from .claude/templates/testing_template.md rename to .claude/templates/testing.md diff --git a/CLAUDE.md b/CLAUDE.md index 5778684..8998adc 100644 --- a/CLAUDE.md +++ b/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 +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 diff --git a/README.md b/README.md index 671c155..c4507c0 100644 --- a/README.md +++ b/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 diff --git a/Dockerfile.backend b/docker/Dockerfile.backend similarity index 100% rename from Dockerfile.backend rename to docker/Dockerfile.backend diff --git a/Dockerfile.frontend b/docker/Dockerfile.frontend similarity index 100% rename from Dockerfile.frontend rename to docker/Dockerfile.frontend diff --git a/docker-compose.yml b/docker/docker-compose.yml similarity index 84% rename from docker-compose.yml rename to docker/docker-compose.yml index 9804dd4..7b339c2 100644 --- a/docker-compose.yml +++ b/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 diff --git a/docs/lessons-learned/001-dependency-version-conflicts.md b/docs/lessons-learned/001-dependency-version-conflicts.md new file mode 100644 index 0000000..6729a2d --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/lessons-learned/002-project-structure-organization.md b/docs/lessons-learned/002-project-structure-organization.md new file mode 100644 index 0000000..c1d1808 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/requirements-backend.txt b/requirements-backend.txt index d14bf2a..4b22fb6 100644 --- a/requirements-backend.txt +++ b/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 diff --git a/requirements-frontend.txt b/requirements-frontend.txt index 5ae5d81..4cd534f 100644 --- a/requirements-frontend.txt +++ b/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 \ No newline at end of file