77 lines
3.0 KiB
Markdown
77 lines
3.0 KiB
Markdown
# 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 |