Docs

md files

How BoardMark stores work as Markdown: project.md, issues, comments and sprints, 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}/p/{project_key}/
  project.md                       # config, board type, statuses, workflow
  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
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_at: 2026-09-23T09:00:00+07:00
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).

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
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, 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
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