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

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

# 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