Repository Standard
Repository Standard
1. The repository as the source of truth
Every relevant project or repository contains normalized technical documentation. This documentation is not optional. It is part of the product.
It answers at least the following questions:
- What is this repository?
- Which system or product does it concern?
- Who owns it?
- What responsibility does it have?
- Which interfaces does it provide?
- Which external and internal dependencies exist?
- Which architectural decisions apply?
- Which C4 diagrams describe it?
- Which quality goals apply?
- Which known risks or technical debts exist?
- Which Jira epics, features, or product areas relate to it?
2. Sample repo structure
The exact structure still has to be defined. A possible target structure:
/docs
/architecture
overview.md
context.md
containers.md
components.md
runtime.md
deployment.md
/adr
0001-use-event-driven-architecture.md
0002-split-billing-service.md
/quality
quality-goals.md
known-risks.md
technical-debt.md
/api
openapi.yaml
asyncapi.yaml
/glossary
glossary.md
architecture.yaml
catalog-info.yaml
mkdocs.yml
README.md
This structure separates human documentation from machine-readable metadata.
3. Machine-readable metadata
In addition to the Markdown documentation, every repository needs machine-readable metadata so AURA does not have to guess what a repository is.
Example:
service:
name: billing-service
owner: team-payments
product: commerce-platform
domain: payments
lifecycle: production
criticality: high
repository:
url: https://git.example.com/commerce/billing-service
default_branch: main
relationships:
depends_on:
- user-service
- payment-provider-adapter
provides:
- billing-api
- invoice-events
contracts:
openapi: docs/api/openapi.yaml
asyncapi: docs/api/asyncapi.yaml
documentation:
overview: docs/architecture/overview.md
c4_context: docs/architecture/context.md
c4_container: docs/architecture/containers.md
adr_folder: docs/adr
quality_goals: docs/quality/quality-goals.md
known_risks: docs/quality/known-risks.md
jira:
project_key: PAY
related_epics:
- PAY-123
- PAY-456
→ Full architecture.yaml template in the templates.
4. Ownership
Every documentation needs clear ownership. For each service, AURA should at least know:
owner: team-payments
reviewers:
- team-payments
- architecture-board
- platform-team
criticality: high
lifecycle: production
Ownership matters for:
- notifications
- reviews
- escalations
- outdated documentation
- architectural decisions
- accountability for critical services
Without ownership, AURA quickly becomes a passive information system without commitment.
5. Jira integration as first-class context
AURA should treat Jira as first-class context and establish the following connections:
Jira epic / story / task
-> pull request
-> commit
-> architectural change
-> ADR
-> affected services
-> central architecture view
This makes questions like the following possible:
- Which services are affected by this epic?
- Which architectural decisions were made for this feature?
- Which PRs changed the architecture?
- Which risks are still attached to this Jira ticket?
- Which teams need to be involved for this feature?
This way, AURA can already help during ticket creation.
6. Repo types
For AURA, it still needs to be defined which repository types are distinguished, because their documentation requirements differ:
- Service repository — productive service with APIs/events, high documentation duty
- Library repository — shared library, lighter documentation standard
- Frontend repository — UI application, focus on backend dependencies and APIs
- Infrastructure repository — IaC, focus on deployment and security documentation
Which files are mandatory per repo type is an open decision.
Continue reading
- Next page: Documentation — Markdown templates, C4, ADRs, quality
- Templates and CLI — full
architecture.yamltemplate - PR Check — how AURA verifies the standard