docs/GUARDRAILS.md

Repository Guardrails & Best Practices

1. Monorepo Structure Integrity

To maintain a clean "One Source of Truth" architecture, the following rules must be strictly enforced:

🚫 Root Directory Restrictions

The root directory must ONLY contain:

• Project configuration (package.json, tsconfig.json, .gitignore, etc.)
• Core documentation (README.md, CONTRIBUTING.md, SECURITY.md)
• Workspace folders (apps/, packages/, docs/, scripts/)

NEVER create:

• Source code folders (src/, utils/, components/) in root.
• Random script files (.py, .sh, .bat) in root.
• Temporary folders (temp/, debug/) in root.

📂 File Placement Guide

Type	Correct Location
Frontend Code	apps/matrix-frontend/src/
Backend Code	apps/backend/src/
Shared Types	packages/domain-types/ or packages/mcp-types/
Shared Logic	packages/shared-utils/ (Future)
Documentation	docs/{category}/ (e.g., docs/architecture/)
Scripts	scripts/
Design Assets	design-references/

2. Development Workflow

📦 Dependency Management

• Root package.json: Only for dev-dependencies (eslint, typescript, vitest) and orchestration scripts.
• App package.json: Application-specific dependencies (react, express, etc.) must live in apps/{app-name}/package.json.

🔄 Single Command Start

Always use the root npm run dev to start the full stack. This ensures all services run in the correct context with correct environment variables.

3. Documentation Standards

• Consolidation: Do not create new .md files in root for status updates. Update existing files in docs/status/.
• Archive: When a feature is complete or a document is obsolete, move it to docs/archive/ instead of leaving it to clutter the active documentation.

4. Automated Enforcement (Future)

To ensure these rules are followed, we will implement:

• Husky Hooks: Pre-commit checks to prevent committing files in root.
• Lint-Staged: Ensure all committed code passes linting.
• CI Checks: Fail build if unauthorized directories appear in root.