template/docs/PROJECT.md

# Project

This document is the source of truth for project intent, scope, runtime facts,
and operational expectations.

For implementation structure, see [ARCHITECTURE.md](ARCHITECTURE.md).
For engineering standards, see [CONVENTIONS.md](CONVENTIONS.md).
For delivery workflow, see [workflow.md](workflow.md).

## Project Identity

| Field | Value |
| --- | --- |
| Project name | `{{PROJECT_NAME}}` |
| Repository | `{{REPOSITORY_URL}}` |
| Primary owner | `{{OWNER}}` |
| Status | `{{STATUS}}` |
| Target users | `{{TARGET_USERS}}` |

## Vision

`{{PROJECT_VISION}}`

Describe the long-term purpose of the project in one or two paragraphs.
The vision should explain why the project exists, not how it is implemented.

## Goals

- `{{GOAL_1}}`
- `{{GOAL_2}}`
- `{{GOAL_3}}`

Goals should be measurable enough to guide trade-offs.

## Non-Goals

- `{{NON_GOAL_1}}`
- `{{NON_GOAL_2}}`

Non-goals prevent accidental scope expansion.

## Functional Requirements

| ID | Requirement | Priority | Status |
| --- | --- | --- | --- |
| FR-001 | `{{FUNCTIONAL_REQUIREMENT}}` | Must | Proposed |

## Non-Functional Requirements

| Category | Requirement | Measurement |
| --- | --- | --- |
| Availability | `{{AVAILABILITY_REQUIREMENT}}` | `{{AVAILABILITY_MEASURE}}` |
| Performance | `{{PERFORMANCE_REQUIREMENT}}` | `{{PERFORMANCE_MEASURE}}` |
| Security | `{{SECURITY_REQUIREMENT}}` | `{{SECURITY_MEASURE}}` |
| Privacy | `{{PRIVACY_REQUIREMENT}}` | `{{PRIVACY_MEASURE}}` |
| Maintainability | `{{MAINTAINABILITY_REQUIREMENT}}` | `{{MAINTAINABILITY_MEASURE}}` |

## Users And Roles

| Role | Description | Key Permissions |
| --- | --- | --- |
| `{{ROLE_NAME}}` | `{{ROLE_DESCRIPTION}}` | `{{ROLE_PERMISSIONS}}` |

## Tech Stack

| Area | Choice | Notes |
| --- | --- | --- |
| Language | `{{LANGUAGE}}` | `{{LANGUAGE_NOTES}}` |
| Framework | `{{FRAMEWORK}}` | `{{FRAMEWORK_NOTES}}` |
| Frontend | `{{FRONTEND}}` | `{{FRONTEND_NOTES}}` |
| Backend | `{{BACKEND}}` | `{{BACKEND_NOTES}}` |
| Database | `{{DATABASE}}` | `{{DATABASE_NOTES}}` |
| Messaging | `{{MESSAGING}}` | `{{MESSAGING_NOTES}}` |
| Search | `{{SEARCH}}` | `{{SEARCH_NOTES}}` |
| Cache | `{{CACHE}}` | `{{CACHE_NOTES}}` |

## Runtime

| Environment | Purpose | URL or Entry Point | Notes |
| --- | --- | --- | --- |
| Local | Development | `{{LOCAL_URL}}` | `{{LOCAL_NOTES}}` |
| Test | Automated validation | `{{TEST_URL}}` | `{{TEST_NOTES}}` |
| Staging | Release verification | `{{STAGING_URL}}` | `{{STAGING_NOTES}}` |
| Production | Live system | `{{PRODUCTION_URL}}` | `{{PRODUCTION_NOTES}}` |

## Frameworks

Document framework-specific expectations here only when they affect how the
project is built, tested, deployed, or maintained.

- `{{FRAMEWORK_CONSTRAINT}}`
- `{{FRAMEWORK_EXTENSION_POINT}}`

## Infrastructure

| Component | Provider | Responsibility | Notes |
| --- | --- | --- | --- |
| Hosting | `{{HOSTING_PROVIDER}}` | `{{HOSTING_RESPONSIBILITY}}` | `{{HOSTING_NOTES}}` |
| Storage | `{{STORAGE_PROVIDER}}` | `{{STORAGE_RESPONSIBILITY}}` | `{{STORAGE_NOTES}}` |
| Network | `{{NETWORK_PROVIDER}}` | `{{NETWORK_RESPONSIBILITY}}` | `{{NETWORK_NOTES}}` |

## Database

| Field | Value |
| --- | --- |
| Database engine | `{{DATABASE}}` |
| Migration tool | `{{MIGRATION_TOOL}}` |
| Backup strategy | `{{BACKUP_STRATEGY}}` |
| Restore strategy | `{{RESTORE_STRATEGY}}` |
| Data retention | `{{DATA_RETENTION}}` |

## CI/CD

| Pipeline | Trigger | Required Checks | Notes |
| --- | --- | --- | --- |
| `{{PIPELINE_NAME}}` | `{{PIPELINE_TRIGGER}}` | `{{PIPELINE_CHECKS}}` | `{{PIPELINE_NOTES}}` |

## Deployment

| Area | Policy |
| --- | --- |
| Deployment strategy | `{{DEPLOYMENT}}` |
| Rollback strategy | `{{ROLLBACK_STRATEGY}}` |
| Release owner | `{{RELEASE_OWNER}}` |
| Change window | `{{CHANGE_WINDOW}}` |

See [release-process.md](release-process.md) for release execution.

## Authentication

| Field | Value |
| --- | --- |
| Authentication method | `{{AUTHENTICATION_METHOD}}` |
| Identity provider | `{{IDENTITY_PROVIDER}}` |
| Session model | `{{SESSION_MODEL}}` |
| Token lifetime | `{{TOKEN_LIFETIME}}` |

## Authorization

| Field | Value |
| --- | --- |
| Authorization model | `{{AUTHORIZATION_MODEL}}` |
| Role source | `{{ROLE_SOURCE}}` |
| Policy location | `{{POLICY_LOCATION}}` |
| Audit requirements | `{{AUTHORIZATION_AUDIT_REQUIREMENTS}}` |

## Logging

| Field | Value |
| --- | --- |
| Logging library | `{{LOGGING_LIBRARY}}` |
| Log sink | `{{LOG_SINK}}` |
| Correlation ID | `{{CORRELATION_ID_POLICY}}` |
| Sensitive data policy | `{{LOG_SENSITIVE_DATA_POLICY}}` |

## Monitoring

| Signal | Tool | Alert Policy |
| --- | --- | --- |
| Availability | `{{AVAILABILITY_TOOL}}` | `{{AVAILABILITY_ALERT_POLICY}}` |
| Errors | `{{ERROR_TOOL}}` | `{{ERROR_ALERT_POLICY}}` |
| Performance | `{{PERFORMANCE_TOOL}}` | `{{PERFORMANCE_ALERT_POLICY}}` |
| Business metrics | `{{BUSINESS_METRICS_TOOL}}` | `{{BUSINESS_ALERT_POLICY}}` |

## Testing

| Test Type | Tooling | Required When |
| --- | --- | --- |
| Unit | `{{UNIT_TEST_TOOL}}` | `{{UNIT_TEST_POLICY}}` |
| Integration | `{{INTEGRATION_TEST_TOOL}}` | `{{INTEGRATION_TEST_POLICY}}` |
| End-to-end | `{{E2E_TEST_TOOL}}` | `{{E2E_TEST_POLICY}}` |
| Performance | `{{PERFORMANCE_TEST_TOOL}}` | `{{PERFORMANCE_TEST_POLICY}}` |
| Security | `{{SECURITY_TEST_TOOL}}` | `{{SECURITY_TEST_POLICY}}` |

## Roadmap

| Milestone | Target | Outcome |
| --- | --- | --- |
| `{{MILESTONE}}` | `{{TARGET_DATE}}` | `{{OUTCOME}}` |

## Open Questions

| Question | Owner | Needed By | Status |
| --- | --- | --- | --- |
| `{{OPEN_QUESTION}}` | `{{QUESTION_OWNER}}` | `{{NEEDED_BY}}` | Open |