A good internal dev-doc structure could be:
Internal Developer Documentation
1. Overview
Purpose of the system, who it is for, and the main mental model.
Include:
What the product/system does
Key domains/concepts
High-level architecture diagram
Main repositories/services/packages
Links to local setup, production dashboards, and issue trackers
2. Architecture
This should be near the top, as you suggested.
2.1 System Architecture
Explain the system at a high level:
Major apps/services
Client/server boundaries
Storage layers
External dependencies
Runtime environments
2.2 Dataflows
Very useful as its own major subsection.
Examples:
“User creates a document”
“Content syncs between peers”
“Identity/auth flow”
“Publishing flow”
“Search/indexing flow”
“Import/export flow”
Each dataflow should ideally include:
Trigger
Components involved
Step-by-step sequence
Data written/read
Failure cases
Relevant files/modules
2.3 Components
Component-by-component reference.
For each component:
## Component Name
### Responsibility
What this component owns.
### Inputs
What it receives.
### Outputs
What it produces.
### Dependencies
Other components/services it relies on.
### Key files
Important files/directories.
### Lifecycle
When/how it starts, updates, shuts down.
### Known gotchas
Things future devs should know.
3. Development Setup
Practical onboarding section.
Include:
Prerequisites
Installing dependencies
Environment variables
Running locally
Common dev commands
Resetting local state
Seeding test data
Troubleshooting setup issues
4. Codebase Guide
A map of the repository.
Example:
/apps
/desktop
/web
/packages
/core
/ui
/sync
/db
/tools
/docs
For each major directory, explain:
What belongs here
What should not go here
Important conventions
Entry points
5. Core Concepts
This is where you define project-specific ideas.
For Seed Hypermedia, this might include things like:
Documents
Blocks
Entities
Accounts/identity
Hypermedia links
Versions/history
Sync state
Local-first state
Publishing
Each concept should answer:
What is it?
Why does it exist?
Where is it represented in code?
How does it move through the system?
6. APIs and Interfaces
Document internal and external APIs.
Include:
Public APIs
Internal service interfaces
RPC methods
Event/message schemas
Database schemas
Type definitions
Error formats
Good pattern:
## API / Method Name
### Purpose
### Request/input
### Response/output
### Side effects
### Errors
### Example
### Related files
7. Storage and Data Model
A dedicated section for persistence.
Include:
Database schema
Local storage layout
File storage
Cache layers
Indexes
Migrations
Backup/restore
Data ownership rules
8. Sync, Networking, and State
Especially important if the system is distributed or local-first.
Include:
Source of truth
Conflict resolution
Offline behavior
Peer/server communication
Retry behavior
Consistency guarantees
Debugging sync issues
9. Testing
Include:
Test strategy
Unit tests
Integration tests
End-to-end tests
Fixtures
Mocks
How to run tests
How to add tests
Known gaps
10. Debugging and Observability
Practical operational docs.
Include:
Logs
Metrics
Tracing
Debug flags
Devtools
Common failure modes
How to inspect local DB/state
Production debugging checklist
11. Build, Release, and Deployment
Include:
Build pipeline
CI/CD
Versioning
Release checklist
Deployment environments
Rollback process
Feature flags
Platform-specific notes
12. Security and Permissions
Include:
Auth model
Permissions model
Secrets
Sensitive data handling
Threat model notes
Common security mistakes
13. Conventions and Patterns
This keeps the codebase consistent.
Include:
Naming conventions
Error handling
State management patterns
Logging conventions
Folder conventions
Dependency rules
UI patterns
API design rules
14. Runbooks
For recurring operational tasks.
Examples:
“How to debug broken sync”
“How to recover from corrupted local state”
“How to inspect a user document”
“How to rotate credentials”
“How to ship a release”
“How to migrate data”
15. Decision Records
Use ADRs: Architecture Decision Records.
Structure:
# ADR 001: Use X for Y
## Status
Accepted / Proposed / Deprecated
## Context
## Decision
## Consequences
## Alternatives considered
This is valuable because internal docs should explain why things are the way they are, not only what exists.
Suggested top-level order
Your instinct is good. I’d structure it like this:
# Internal Dev Documentation
1. Overview
2. Architecture
2.1 System Architecture
2.2 Dataflows
2.3 Components
3. Development Setup
4. Codebase Guide
5. Core Concepts
6. APIs and Interfaces
7. Storage and Data Model
8. Sync, Networking, and State
9. Testing
10. Debugging and Observability
11. Build, Release, and Deployment
12. Security and Permissions
13. Conventions and Patterns
14. Runbooks
15. Architecture Decision Records
For the top of the docs, I’d use this exact order:
# Internal Dev Documentation
## Overview
## Architecture
## Dataflows
## Components
But I’d make Dataflows and Components subsections under Architecture unless they become large enough to deserve their own top-level pages.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime