# Design documents (API design and database design)

Once requirement cards and requirements are settled, you build the **design documents** that implementation stands on. They are managed from '**Design docs**' under 'Planning and design' in the left menu.

![PM on Rails design documents. API and database drafts. Before: design lived in slides and conversation. After: people review a draft expanded from the story.](https://pmonrails.com/docs-img/basic-design.png)

## Kinds of design document

| Kind | Roughly what goes in it |
| --- | --- |
| **API design document** | Endpoint list, requests / responses, sequence diagrams |
| **Database design document** | ER diagram, outline of the table definitions, key / index policy |
| **Screen design document** | Screen list, transitions, fields |

The design docs screen manages documents in one folder per genre. There are genres such as database design, API design, screen design and report design, and you can add your own. The list shows the name, who it is shared with, the last update and the kind.

## How to create one

- Create a new one from 'Create design doc' at the top right. The content works on the same mechanism as a [knowledge](https://pmonrails.com/en/docs/knowledge.md) document, so **version history, review / approval and search** all apply as-is.
- **Have AI draft it** — on the new document screen, open the side chat from **"Write with AI"**. Pick a template and diagram type to generate a draft such as an endpoint table or an ER diagram from the project's requirement cards and requirements (check and edit it before saving).
- **You can draw mermaid diagrams** — Write a ```mermaid code block in the body and **ER diagrams (`erDiagram`) and sequence diagrams (`sequenceDiagram`) are rendered as diagrams**. Use them for the ER diagram in a database design and the sequence diagram in an API design (this documentation site uses the same rendering).

## Where it sits

- A design document is an **internal implementation reference**. Its default visibility is inside the workspace, so it is not shown to stakeholders (viewers).
- It carries no hard link hanging directly off a requirement, but because the AI draft is built by reading requirement cards and requirements, the content follows the project's requirements.

## Next steps

- [Task management](https://pmonrails.com/en/docs/tasks.md) / [Claude Web, Claude Code and MCP integration](https://pmonrails.com/en/docs/mcp.md)

---

https://pmonrails.com/en/docs/basic-design