Onboarding Document Template
README.md - Full Template
# [Project Name]
> One-sentence description of what this does and who uses it.
[](https://github.com/org/repo/actions/workflows/ci.yml)
[](https://codecov.io/gh/org/repo)
## What is this?
[2-3 sentences: problem it solves, who uses it, current state]
**Live:** https://myapp.com
**Staging:** https://staging.myapp.com
**Docs:** https://docs.myapp.com
---
## Quick Start
### Prerequisites
| Tool | Version | Install |
|------|---------|---------|
| Node.js | 20+ | `nvm install 20` |
| pnpm | 8+ | `npm i -g pnpm` |
| Docker | 24+ | [docker.com](https://docker.com) |
| PostgreSQL | 16+ | via Docker (see below) |
### Setup (5 minutes)
```bash
git clone https://github.com/org/repo
cd repo
pnpm install
docker compose up -d
cp .env.example .env
pnpm db:migrate
pnpm db:seed
pnpm dev
pnpm test
Verify it works
Architecture
System Overview
Browser / Mobile
|
v
[Next.js App] <- [Auth]
|
+-> [PostgreSQL]
+-> [Redis]
+-> [S3]
Tech Stack
| Layer |
Technology |
Why |
| Frontend |
Next.js |
SSR + routing |
| Styling |
Tailwind + shadcn/ui |
Rapid UI |
| API |
Route handlers |
Co-location |
| Database |
PostgreSQL |
Relational |
| Queue |
BullMQ + Redis |
Background jobs |
Key Files
| Path |
Purpose |
app/ |
Pages and route handlers |
src/db/ |
Schema and migrations |
src/lib/ |
Shared utilities |
tests/ |
Test suites and helpers |
.env.example |
Required variables |
Common Developer Tasks
Add a new API endpoint
touch app/api/my-resource/route.ts
touch tests/api/my-resource.test.ts
Run a database migration
pnpm db:generate
pnpm db:migrate
Add a background job
# Create worker module and enqueue path
Debugging Guide
Common Errors
- Missing environment variable
- Database connectivity failure
- Expired auth token
- Generic 500 in local dev
Useful SQL Queries
- Slow query checks
- Connection status
- Table bloat checks
Log Locations
| Environment |
Logs |
| Local dev |
local terminal |
| Production |
platform logs |
| Worker |
worker process logs |
Contribution Guidelines
Branch Strategy
main protected- feature/fix branches with ticket IDs
PR Requirements
- CI green
- Tests updated
- Why documented
- Self-review completed
Commit Convention
feat(scope): ...fix(scope): ...docs: ...
Audience-Specific Notes
Junior Developers
- Start with core auth/data modules
- Follow tests as executable examples
Senior Engineers
- Read ADRs and scaling notes first
- Validate performance/security assumptions early
Contractors
- Stay within scoped feature boundaries
- Use wrappers for external integrations
## Usage Notes
- Keep onboarding setup under 10 minutes where possible.
- Include executable verification checks after each setup phase.
- Prefer links to canonical docs instead of duplicating long content.
- Update this template when stack conventions or tooling change.
1851c8fb09