Monorepo Folder Cleanup and Environment Organization
Problem
Development environment accumulated multiple organizational structures (flat ap-apps/ alongside cc/ monorepo), duplicated project directories, and unclear boundaries between active development, experiments, and tooling.
Solution
A “Three-Bucket Strategy” that separates concerns by lifecycle stage and governance level.
Architecture
Zone-Based Organization
| Zone | Purpose | Governance |
|---|---|---|
apps/ | Active, compliant applications | Must pass compliance checks |
lab/ | Research and experiments | Unrestricted |
staging/ | New repos under evaluation | Entry point for all new work |
library/ | Knowledge bases and documentation | Append encouraged |
infra/ | Infrastructure and tooling | Caution required |
Key Principles
- New repos start in staging — Graduate to
apps/only after passing compliance - No duplication — Single source of truth per project; eliminate shadow copies
- Universal file structure — Every repo follows the same
.management/pattern - Cross-device sync — Use Syncthing or similar for development artifacts
- DevContainers — Standardize development environments
Adopting External Projects
When bringing in codebases developed elsewhere:
- Clone into
staging/ - Audit structure against organizational standards
- Add required
.management/files - Run compliance checks
- Graduate to
apps/only when passing
Cleanup Protocol
- Map current state —
find . -maxdepth 3 -type dto audit directory trees - Identify duplicates — Flag directories that appear in multiple locations
- Consolidate — Merge into canonical locations
- Archive — Move deprecated code to
archive/rather than deleting - Verify — Confirm all tools and scripts reference new paths
Related
- poc-directory-structure — Standard structure for proof-of-concept projects
- graduation-criteria — Criteria for promoting projects to production status