Workspace Design
Define a repository layout and naming system that stays understandable as the project grows.
Workspace design is the map developers use every day. Good structure reduces onboarding time, prevents accidental coupling, and helps automation understand what changed.
Suggested Layout
| Path | Role |
|---|---|
apps/ | Deployable applications and services |
packages/ | Shared libraries and internal packages |
tooling/ or scripts/ | Repository automation |
docs/ | Architecture records and operating docs |
.github/ or CI directory | Workflow definitions |
Naming Rules
- App names should describe product or runtime responsibility.
- Package names should describe capability, not implementation detail.
- Avoid generic names such as
common,shared, orutilsunless scope is very clear. - Use consistent package prefixes for internal ownership and publishing policy.
- Keep route names, package names, and dashboard names aligned where possible.
Workspace Review
| Check | Pass condition |
|---|---|
| Discoverability | A new engineer can find the right app or package quickly |
| Dependency direction | Apps consume packages in a predictable direction |
| Ownership | Each workspace has a maintainer |
| Build scope | Tasks can run only for affected workspaces |
| Documentation | Each major workspace explains purpose and local commands |
Change Policy
Structural changes should be reviewed as architecture changes. Moving a package, renaming an app, or changing dependency direction affects CI, imports, ownership, and developer habits.