Documentation Templates

These templates are designed to be copy/pasteable into projects.

Module docs entrypoint (`<module>/docs/index.md`)

# <Module Name> Docs

## Overview

What this module is, who it serves, and what it owns.

## Quick links

- Overview: `./overview.md`
- Local setup: `./local_setup.md`
- Architecture: `./architecture.md`
- Operations: `./operations.md`
- Troubleshooting: `./troubleshooting.md`

## Standards (cross-project)

When you need conventions, link to the centralized standards site instead of duplicating:
- Engineering standards (root): https://docs.flowcreate.solutions/
- Security standards: https://docs.flowcreate.solutions/backend/security/overview/
- Testing standards: https://docs.flowcreate.solutions/backend/testing/overview/
- Database standards (if applicable): https://docs.flowcreate.solutions/backend/database/module-structure/

## Module-specific notes

Project-specific details that change frequently (ports, env vars, commands).

Module overview (`<module>/docs/overview.md`)

# <Module Name> Overview

## What this module is

One paragraph describing the purpose and boundaries.

## Responsibilities

- <What it owns>
- <What it does not own>

## Key workflows

- <Workflow 1>
- <Workflow 2>

## Constraints and tradeoffs

- <Constraint>
- <Tradeoff>

## Standards references

Link to standards pages for conventions used here.

Local setup (`<module>/docs/local_setup.md`)

# <Module Name> Local Setup

## Prerequisites

- <Runtime + version>
- <Package manager>
- <DB/queue/etc.>

## Environment variables

This repo provides `.env.example`. Copy it to `.env` and fill in values.

## Install

```bash
<install command>

Run locally

<run command>

Verify

<Health check endpoint / smoke test>


## Architecture (`<module>/docs/architecture.md`)

```md
# <Module Name> Architecture

## Diagram

<Add a simple diagram or bullet topology>

## Key boundaries

- <Boundary 1>
- <Boundary 2>

## Data flows

- <Flow 1>
- <Flow 2>

## Standards references

Link to standards pages for architectural conventions.

Operations (`<module>/docs/operations.md`)

# <Module Name> Operations

## Health

- How to check health
- Dependencies required for healthy state

## Observability

- Logs: <where/how>
- Metrics: <where/how>
- Traces: <where/how>
- Error tracking: <where/how>

## Deploy

- How to deploy (high level)
- How to verify success

## Rollback

- How to rollback safely
- Known risky steps

## Common incidents

### Symptom: <describe>

- Likely causes:
  - <cause>
- Checks:
  - <check>
- Actions:
  - <action>
- Escalation:
  - <when/who>

Troubleshooting (`<module>/docs/troubleshooting.md`)

# <Module Name> Troubleshooting

## Quick checks

- Confirm environment variables loaded
- Confirm dependencies running (DB/queue/etc.)
- Confirm service is reachable

## Common issues

### <Symptom>

- Likely causes:
  - <cause>
- Fix:
  - <steps>

ADR template (`docs/decisions/YYYYMMDD_short_title.md`)

# ADR: <Title>

Date: YYYY-MM-DD

## Context

What problem are we solving and why now?

## Decision

What did we choose?

## Alternatives considered

- <Alternative 1>: why not
- <Alternative 2>: why not

## Consequences

- Positive:
  - <benefit>
- Negative:
  - <cost>
- Follow-ups:
  - <action>

## Links

- PR: <link>
- Issue: <link>
- Docs: https://docs.flowcreate.solutions/

Pull Request template (`.github/pull_request_template.md`)

Copy this into a repo to standardize PRs and enforce the SDLC checklist. See: Backend → Development → SDLC Governance.

## Summary
- What changed and why?

## Risk
- What could break? Blast radius?

## Verification
- [ ] black / formatter
- [ ] flake8 / linter
- [ ] mypy / type-check
- [ ] pytest
- [ ] Manual smoke test (if applicable): <steps>

## Security
- [ ] Auth/authz/tenant isolation unchanged or intentionally updated
- [ ] No secrets/logging leaks introduced

## Docs
- [ ] Docs updated (or not needed): <link/reason>