# Documentation Maintenance

## Recommended Documentation Model

Do not maintain one Markdown file per Python script as the primary documentation model. This service is schema-driven, so endpoint behavior is spread across:

- Python execution engine
- S3 route schema
- S3 auth schema
- merchant/category/admin endpoint schemas
- MySQL tables
- external integrations

Script-by-script docs are useful as secondary reference, but they will not explain what an endpoint actually does.

Use topic-based docs instead:

| Topic | File |
| --- | --- |
| Service summary | `documentation/overview.md` |
| Request lifecycle and architecture | `documentation/architecture.md` |
| Local/container setup | `documentation/setup.md` |
| S3 schema format and review checklist | `documentation/schemas.md` |
| Operation reference | `documentation/operations.md` |
| Resolver and state reference | `documentation/key-resolution.md` |
| Database behavior | `documentation/database.md` |
| Endpoint contracts | `documentation/endpoints/*.md` |
| External integrations | `documentation/integrations/*.md` |
| Debugging and release checklist | `documentation/runbook.md` |

## When To Add Endpoint Docs

Create or update an endpoint doc whenever:

- a new route is added
- request schema changes
- auth behavior changes
- business rules change
- persistence changes
- response shape changes
- external API side effects change

Use:

```text
documentation/endpoints/template.md
```

## When To Update Reference Docs

Update `operations.md` when:

- a new operation is added to `operations.py`
- an existing operation changes behavior
- a schema begins using an operation in a new pattern

Update `key-resolution.md` when:

- a new resolver prefix is added
- a shared state key becomes part of endpoint contracts
- component call behavior changes

Update `database.md` when:

- new tables are written
- query builder behavior changes
- raw query conventions change
- result shape assumptions change

Update integration docs when:

- API URL, payload, auth, timeout, or fallback behavior changes
- generated files or DB side effects change
- new external services are introduced

## Suggested PR Checklist

Every feature PR should answer:

- Did any S3 route/auth/endpoint schema change?
- Which endpoint docs were updated?
- Did this add or change a DB write?
- Did this add or change an external API call?
- Did this add a new state key?
- Did this add a new operation or static function?
- Were success and failure responses documented?

## Suggested Endpoint Documentation Naming

Use lowercase kebab-case based on the route name:

| Route | Doc file |
| --- | --- |
| `/api/create-customer` | `documentation/endpoints/create-customer.md` |
| `/api/product-list` | `documentation/endpoints/product-list.md` |
| `/api/upload-document` | `documentation/endpoints/upload-document.md` |

## Source Of Truth Rule

For endpoint behavior, the S3 schemas are the source of truth. Documentation should describe the schema behavior, not just the Python helper that executes it.

If documentation and schema disagree, update the documentation or the schema immediately in the same feature change.