Documentation

This directory is the single source of truth for all project documentation. There is no published mirror — the previous cotton-coveris-mvp-docs site is retired.

These files are authored and read as an Obsidian vault: internal links use [[wikilinks]], each note carries title/tags properties, and the graph view is the map of the project.

Start here: [[PRD]]

The PRD is the primary document. It defines what Coveris is, what it must do, and the boundaries of the MVP. Everything else in this directory supports or elaborates on it.

Index

Product & Architecture

File	Purpose
[[PRD]]	Product requirements — scope, modules, domain model, business rules
[[adr/README	adr/]]
[[backlogs/README	backlogs/]]

Stack

Folder hub: [[stack/README|stack/]]

File	Purpose
[[overview	stack/overview]]
[[frontend	stack/frontend]]
[[backend	stack/backend]]
[[auth	stack/auth]]
[[design-system	stack/design-system]]
[[business-rules	stack/business-rules]]
[[api-conventions	stack/api-conventions]]

Development

Folder hub: [[dev/README|dev/]]

File	Purpose
[[dev/requirements	dev/requirements]]
[[dev/environment	dev/environment]]
[[setup	dev/setup]]
[[docker	dev/docker]]
[[workflow	dev/workflow]]
[[admin	dev/admin]]
[[mock-data	dev/mock-data]]
[[testing	dev/testing]]

Important:

install the obsidian-mcp ASAP and make sure it's working

Production

Folder hub: [[prod/README|prod/]]

File	Purpose
[[prod/requirements	prod/requirements]]
[[prod/environment	prod/environment]]
[[aws	prod/aws]]
[[migrations	prod/migrations]]
[[security	prod/security]]

Authoring these docs (Obsidian vault)

docs/ is the project SSOT, authored as an Obsidian vault whose root is this folder. There is no published mirror — the previous cotton-coveris-mvp-docs site is retired — so we use Obsidian-native syntax (wikilinks, properties, callouts), not GitHub relative links.

Linking

Use wikilinks, never relative Markdown links.

Want	Write	Don’t write
Link to a unique note	`[[overview]]`	`[stack/overview.md](./stack/overview.md)`
Link with custom text	`[[overview\|the stack]]`	`[the stack](./stack/overview.md)`
Link to a heading	`[[adr-008-authentication#Decision]]`	—

Duplicate basenames must be path-qualified. Obsidian identifies a note by filename only, so same-named files (README, environment, requirements) collide. Qualify with the folder path and give each a unique alias in frontmatter:

[[dev/environment|dev environment]]
[[prod/environment|prod environment]]

Root specs. PRD.md and API.md are project SSOT at the repo root, surfaced inside the vault as symlinks (docs/PRD.md, docs/API.md) so [[PRD]]/[[API]] resolve and both stay indexed. Edit the root originals, never the symlinks.

Properties (frontmatter)

Every note starts with YAML. title drives the graph node label (Front Matter Title plugin) — this is why docs/README.md shows as “Documentation”, not “README”. tags map to graph color groups — keep to the controlled set: docs, adr, backlog, stack, dev, prod, proposal.

---
title: Human Readable Title
tags:
  - dev
aliases:            # only for duplicate-basename notes
  - dev-environment
---

Folder notes

A README.md inside a folder is its folder note (Folder Notes plugin): clicking the folder in the file tree opens it, and it displays as the folder name. Every folder hub — docs/, adr/, dev/, prod/, stack/ — has one, tagged with that folder’s color group.

Callouts

Use callouts for asides: > [!note], > [!warning], > [!todo], > [!example]. Empty stub notes carry > [!todo] Stub — not yet written. so the graph shows what’s pending.

Required plugins

Both are listed in .obsidian/community-plugins.json (install once via Settings → Community plugins → Browse):

Folder Notes (folder-notes) — recognizes README as the folder note; settings pre-staged in .obsidian/plugins/folder-notes/data.json.
Front Matter Title (obsidian-front-matter-title-plugin) — after install, enable the Graph and Explorer features pointing at the title key.

The graph view is scoped to the whole vault with color groups by tag — see .obsidian/graph.json. For the full Obsidian-Markdown syntax reference, see the obsidian-markdown skill.