Obstacle: Uncertain about hierarchical structure for scalability vs simplicity

[amaralc]

Obstacle Description

Currently unsure about what hierarchical structure to follow to ensure scalability of the project while maintaining a simple structure.

Given a growing PeerLab monorepo with multiple teams (kernel, people, things, web)
When adding new services, libraries, or domain areas
Then uncertain about optimal folder nesting, module organization, and dependency boundaries

Why It Blocks Progress

This uncertainty blocks progress because:

• Without clear structural guidelines, new team members may create inconsistent patterns
• Ambiguous boundaries could lead to circular dependencies or tight coupling
• Ad-hoc decisions on folder depth and naming conventions may cause later refactoring
• The project might outgrow its structure if not planned for scalability from the start

Suggested Experiments

• Document the current architectural rationale behind teams/{domain}/{service} structure
• Create ADR (Architecture Decision Record) for folder depth limits and naming conventions
• Identify pain points in current structure by reviewing recent refactoring efforts
• Compare against other monorepo patterns (Nx examples, successful projects) to validate approach
• Run a spike to test adding a new domain area and observe friction points
• Define clear criteria for when to split/merge services or create new team domains

[linear]

PEE-54