Docs

md files

How BoardMark stores work as Markdown: project.md, issues, comments, sprints and project docs, with frontmatter, versions and history.

Why store work as md files?
How are the files laid out?
What does an issue file look like?
How are comments stored?
How do versions and history work?

Why store work as md files?

md files are readable by people and AI alike, work with ordinary tools and keep a full change history. The database is only an index for search and boards, and can always be rebuilt from the files.

Data that is not work content — members, teams, access, seats, billing — lives in the database as usual.

How are the files laid out?

Layout in object storage

/c/{company_id}/company/brief/{slug}.md  # company brief
/c/{company_id}/p/{project_key}/
  project.md                       # config, board type, statuses, workflow
  docs/brief/{slug}.md             # project docs: brief,
  docs/notes/{slug}.md             #   working notes
  docs/handoffs/H-{n}.md           #   and handoffs
  sprints/S-{n}.md
  issues/{KEY}-{n}.md              # 1 issue = 1 file
  issues/{KEY}-{n}/comments/{seq:04d}.md

What does an issue file look like?

The frontmatter is validated by the same JSON Schema for the web app and MCP; the body is Markdown, written in the rich-text editor or edited directly.

issues/APP-101.md

---
id: APP-101
type: task                # epic | task | subtask | bug
priority: medium          # highest | high | medium | low | lowest (default medium)
status: in_progress       # must be one of project.md statuses
assignee: usr_01H...      # user id or null
reporter: usr_01H...
points: 3                 # nullable
sprint: S-12              # nullable (Kanban and pipeline = null)
parent: APP-90             # nullable; a subtask needs a parent
links:
  - { type: blocks, id: APP-77 }
  - { type: relates, id: APP-80 }
labels: [frontend]
rank: a0V                 # order on the board and in the backlog
created_by: usr_01H...    # created_by / updated_by: set by the server
created_at: 2026-09-23T09:00:00+07:00
updated_by: usr_01H...
updated_at: 2026-09-23T10:12:00+07:00
version: 14               # optimistic lock, +1 on every write
---
# Login page

Written in the rich-text editor, saved as Markdown:
mermaid, code, tables, checklists and images.

How are comments stored?

One comment is one file. When it came from an AI agent, the agent field names the token used. A reply stores reply_to (the thread's top-level comment) and in_reply_to (the exact comment answered). An edit raises version and sets updated_at / updated_by; a delete keeps the file with an empty body and deleted: true, so the numbering and replies stay. A mention is the link [@Name](mention:usr_…) in the body.

issues/APP-101/comments/0005.md

---
seq: 5
author: usr_01H...
agent: tok_01H...         # null when a person wrote it; set when it came through MCP
created_at: 2026-09-23T10:12:00+07:00
updated_at: 2026-09-23T10:20:00+07:00  # set when the author edits it
updated_by: usr_01H...
version: 2                # +1 on every edit; missing = 1
reply_to: 3               # the thread's top-level comment; null on a top-level comment
in_reply_to: 4            # the exact comment answered
attachments:
  - attachments/APP-101/8f2a-spec.png
---
Fixed in the attached build — [@Somchai](mention:usr_01H...) please re-test.

How do versions and history work?

Every write sends the version it read (optimistic locking)
Every write creates one commit: who, which agent token, which files — and for an AI agent also which client, OAuth or token, which MCP tool and a request id
History and diffs are available over MCP (get_history, diff); in the app, issues changed by an agent are badged and the Agent & MCP page lists your agents' recent commits