Project Onboarding Template

Template for creating project-specific onboarding docs. Copy, fill in, delete unused sections.

TL;DR

How to use:

Copy this template to your project
Fill in each section (delete guidance text)
Remove sections that don't apply
Keep it updated - stale docs are worse than no docs

Prerequisite: New joiners should read Engineering Principles first.

Access Checklist

Before you start:

- [ ] GitHub org access
- [ ] Cloud provider console access
- [ ] Added to Slack channels: #[channel-1], #[channel-2]
- [ ] Added to Linear/Jira project
- [ ] VPN configured (if applicable)
- [ ] [Other access requirements]

Repositories

Repo	What It Is	Setup Guide
`repo-name`	One-line description	README
`repo-name`	One-line description	README

Which repo do I work in?

Building feature X → repo-name
Fixing bug in Y → repo-name
Infrastructure changes → repo-name

Local setup instructions live in each repo's README. This doc covers the bigger picture.

Project Overview

What We Do


Problem we solve	What pain point does this address?
Users	Who uses this? Internal? External? Both?
Business context	Why does this matter to the company?

Key Metrics

Metric	Current	Target	Dashboard
API latency p95	450ms	<200ms	Grafana
Error rate	0.5%	<0.1%	Grafana
Daily active users	12k	20k	Metabase

Architecture

┌─────────┐     ┌─────────┐     ┌─────────┐
│ Client  │────▶│   API   │────▶│   DB    │
└─────────┘     └─────────┘     └─────────┘
                    │
                    ▼
              ┌─────────┐
              │ Queue   │
              └─────────┘

Key components:

API Gateway: Routes requests, handles auth
Worker Service: Processes background jobs
Database: PostgreSQL for transactional data

External dependencies:

Stripe: Payment processing
SendGrid: Transactional email

Codebase Guide

Directory Structure

/
├── src/
│   ├── api/          # HTTP handlers and routes
│   ├── services/     # Business logic
│   ├── repositories/ # Data access
│   └── utils/        # Shared utilities
├── tests/            # Test files mirror src/ structure
├── scripts/          # Build and deployment scripts
└── docs/             # Additional documentation

Key Files

Read these first:

File	Why
`src/api/routes.ts`	Entry point, all routes
`src/services/payment.ts`	Core business logic example
`src/repositories/base.ts`	Data access patterns

Coding Patterns

Service pattern:

typescript

// Services contain business logic, receive dependencies via constructor
class PaymentService {
  constructor(
    private paymentRepo: PaymentRepository,
    private stripe: StripeClient
  ) {}

  async processPayment(orderId: string): Promise<Payment> {
    // Business logic here
  }
}

Error handling:

typescript

// Use custom errors with codes, not generic errors
throw new AppError('PAYMENT_FAILED', 'Card declined', { orderId });

Development Workflow

Branch Naming

[type]/[ticket-id]-[short-description]

feat/PROJ-123-add-payment-method
fix/PROJ-456-null-pointer-checkout
refactor/PROJ-789-extract-validator

Running Tests

bash

# All tests
npm test

# Unit tests only
npm run test:unit

# Integration tests
npm run test:integration

# Single test file
npm test -- --grep "PaymentService"

# With coverage
npm run test:coverage

Building

bash

# Development build
npm run dev

# Production build
npm run build

# Type checking
npm run typecheck

# Linting
npm run lint

Deploying

Environment	Branch	How	Who Can
Local	any	`npm run dev`	Everyone
Staging	main	Auto on merge	Everyone
Production	main	Manual approval	Tech lead +

Deployment checklist:

- [ ] Tests passing
- [ ] PR approved
- [ ] Feature flagged if incomplete
- [ ] Monitoring dashboard open
- [ ] Rollback plan ready

Observability

Dashboards

Dashboard	What It Shows
Service Health	Latency, error rate, throughput
Business Metrics	Orders, revenue, users
Infrastructure	CPU, memory, connections

Key Alerts

Alert	What It Means	First Response
High Error Rate	>5% of requests failing	Check recent deploys, then logs
Latency Spike	p95 >2s	Check DB connections, external APIs
Queue Backup	>1000 pending jobs	Check worker health, scale up

Logs

bash

# Access logs (example with CloudWatch)
aws logs tail /project/api --follow

# Useful queries
service:api level:error    # All API errors
traceId:abc123             # Specific request
userId:user-456            # User's activity

Traces

Tool: Jaeger
Access: https://jaeger.internal.company.com
Key traces: Checkout flow, payment processing, user signup

Common Tasks

Add a New API Endpoint

bash

# 1. Create handler in src/api/handlers/
touch src/api/handlers/newFeature.ts

# 2. Add route in src/api/routes.ts
# router.post('/new-feature', newFeatureHandler);

# 3. Add service if needed
touch src/services/newFeature.ts

# 4. Write tests
touch tests/api/newFeature.test.ts

# 5. Run tests and submit PR
npm test && git add . && git commit -m "feat: add new feature endpoint"

Run a Database Migration

bash

# 1. Create migration
npm run migration:create -- --name add_user_preferences

# 2. Edit the migration file in migrations/

# 3. Run locally
npm run migration:run

# 4. Verify
npm run migration:status

# 5. Deploy (migrations run automatically on deploy)

Debug a Production Issue

Check alerts dashboard for symptoms
Find relevant logs using traceId from alert
Check recent deploys (was anything deployed?)
Look at traces for slow spans
Check external dependencies status pages
Mitigate (feature flag off, rollback, scale up)
Investigate root cause after bleeding stops

Troubleshooting

"Cannot connect to database"

Symptoms: App fails to start, "ECONNREFUSED" errors

Cause: Database not running or wrong connection string

Fix:

bash

# Check if DB is running
docker ps | grep postgres

# Start if not running
docker-compose up -d postgres

# Verify connection string in .env
DATABASE_URL=postgres://user:pass@localhost:5432/dbname

"Tests timeout on CI"

Symptoms: Tests pass locally, timeout on CI

Cause: Missing test database setup or race conditions

Fix:

bash

# Ensure CI runs migrations
npm run migration:run --env=test

# Check for async cleanup issues
# Add afterEach(() => cleanup()) in test files

"Build fails with type errors"

Symptoms: npm run build fails, local dev works

Cause: Dev mode is lenient, build is strict

Fix:

bash

# Run typecheck locally first
npm run typecheck

# Fix all errors before pushing

Team

People

Role	Person	Ask Them About
Tech Lead	@name	Architecture, priorities
Backend	@name	API design, database
Frontend	@name	UI, React patterns
DevOps	@name	Infrastructure, deploys

Communication

Channel	Purpose
#project-dev	Day-to-day development
#project-alerts	Automated alerts
#project-support	Customer issues

Meetings:

Standup: Daily 9:30am (async in Slack on Fridays)
Sprint Planning: Monday 10am
Retro: Every other Friday 3pm

On-Call

Rotation: PagerDuty
Escalation: Page on-call → Tech lead → Engineering manager
Runbooks: Notion/Confluence

Links & Resources

Internal

Resource	Where
Wiki	Confluence
Design Docs	Google Drive
ADRs	GitHub
Runbooks	Notion

External

Resource	Link
Framework Docs	NestJS
Database	PostgreSQL
Cloud Provider	AWS

First Week Checklist

Day 1

[ ] Read this doc
[ ] Get access (see checklist above)
[ ] Clone repos and run local setup
[ ] Join Slack channels
[ ] Meet with buddy/mentor

Day 2-3

[ ] Read key files listed above
[ ] Run the test suite
[ ] Pick up a "good first issue"
[ ] Shadow a PR review

Day 4-5

[ ] Submit first PR
[ ] Join a debugging session or incident review
[ ] Update this doc with anything unclear or missing

Common Mistakes

Mistake	Fix
Skipping local tests	Always run `npm test` before pushing
Forgetting feature flags	Wrap incomplete work in flags
Missing migrations	Check `npm run migration:status` before deploying
Not checking dashboards after deploy	Keep Grafana open for 15 minutes post-deploy
Asking questions without context	Include error messages, what you tried, expected vs actual

Feedback

This doc should help you get productive fast. If something is:

Missing: Add it
Wrong: Fix it
Confusing: Clarify it

Don't ask permission. Just improve it and submit a PR.

Related:

Engineering Principles - Universal engineering practices
Engineering Fundamentals - Technical concepts
Pull Requests - PR guidelines

Project Onboarding Template ​

TL;DR ​

Access Checklist ​

Repositories ​

Project Overview ​

What We Do ​

Key Metrics ​

Architecture ​

Codebase Guide ​

Directory Structure ​

Key Files ​

Coding Patterns ​

Development Workflow ​

Branch Naming ​

Running Tests ​

Building ​

Deploying ​

Observability ​

Dashboards ​

Key Alerts ​

Logs ​

Traces ​

Common Tasks ​

Add a New API Endpoint ​

Run a Database Migration ​

Debug a Production Issue ​

Troubleshooting ​

"Cannot connect to database" ​

"Tests timeout on CI" ​

"Build fails with type errors" ​

Team ​

People ​

Communication ​

On-Call ​

Links & Resources ​

Internal ​

External ​

First Week Checklist ​

Day 1 ​

Day 2-3 ​

Day 4-5 ​

Common Mistakes ​

Feedback ​

Project Onboarding Template

TL;DR

Access Checklist

Repositories

Project Overview

What We Do

Key Metrics

Architecture

Codebase Guide

Directory Structure

Key Files

Coding Patterns

Development Workflow

Branch Naming

Running Tests

Building

Deploying

Observability

Dashboards

Key Alerts

Logs

Traces

Common Tasks

Add a New API Endpoint

Run a Database Migration

Debug a Production Issue

Troubleshooting

"Cannot connect to database"

"Tests timeout on CI"

"Build fails with type errors"

Team

People

Communication

On-Call

Links & Resources

Internal

External

First Week Checklist

Day 1

Day 2-3

Day 4-5

Common Mistakes

Feedback