Status: [🔴 Alpha / 🟡 Beta / 🟢 Production]
Service Owner: [Team Name / Squad]
Mattermost Channel: [#project-channel]

A concise, high-level description of what this project achieves. Explain the "Value Proposition"—why does this code exist and who are its primary users?

• Feature A: Brief description.
• Feature B: Brief description.
• API/Interface: [e.g., REST API / GraphQL / CLI Tool].

• Runtime: [e.g., Python 3.11+, Node.js 20]
• Primary Frameworks: [e.g., FastAPI, React, PyTorch]
• Databases: [e.g., PostgreSQL, Redis, Pinecone]
• Infrastructure: [e.g., AWS ECS, Terraform, Kubernetes]

Ensure you have the following installed:

• [Tool 1] (e.g., Docker Desktop)
• [Tool 2] (e.g., uv, npm, or Go)
• [Tool 3] (e.g., AWS CLI configured with dev profile)

# Clone the repository
git clone [https://github.com/OWNER/REPO.git](https://github.com/OWNER/REPO.git)
cd REPO

# Install dependencies
uv sync

# Running a script / code
# Example: uv run python main:app --reload
uv run [command]

Never commit sensitive credentials to the repository.

• Local Secrets: Managed via .env (ignored by git).

• Team Secrets: Access can be requested via [e.g., Passbolt].

• Key Variables: List critical variables here (e.g., DATABASE_URL, API_KEY).

Use pre-commit to run linters, formatters and other checks locally and in CI. Add a .pre-commit-config.yaml at the repo root to define hooks (e.g., ruff).

For details on our pre-commit configuration and usage, see this Notion page.

• Start App: [Command, e.g., uv run command]

• Run Tests: [Command, e.g., uv run pytest]

• Format Code: [Command, e.g., uv run black . or uv run eslint --fix]

├── .github/              # GitHub Actions, PR Templates, Copilot Instructions
├── docs/                 # Detailed technical documentation & ADRs
├── src/                  # Main application source code
│   ├── api/              # Controllers/Route handlers
│   ├── services/         # Business logic layer
│   └── infrastructure/   # Database clients/External wrappers
├── tests/                # Unit, Integration, and E2E suites
├── scripts/              # Automation, migrations, and seed scripts
└── CHANGELOG.md          # History of all notable changes (SemVer)
└── README.md             # Readme for the whole project

• Logs: [Link to Logfire]

• Error Tracking: [Link to Sentry / Honeybadger]

• Dashboards: [Link to Grafana / Quicksight]

This is a joint repository. To maintain quality and speed, please follow these rules:

• Branching: Please refer to branching strategy found here

• Pull Requests: Fill out the PR Template completely.

• Changelog: Every PR must update the [Unreleased] section of the CHANGELOG.md. Changelog template can be found here

• AI Tools: Use GitHub Copilot for reviews. Refer to .github/copilot-instructions.md for team-specific prompts.

• Documentation: [Link to Confluence / Notion / SoW]

• Architecture ADRs: Found in /docs/adr/.

• Stakeholders: [Name/Department]

• Common Issue 1: "Description of issue." -> Fix: Run command X.

• Common Issue 2: "Description of issue." -> Fix: Check config Y.