Developer Onboarding Guide

Welcome to the Team! 🚀

This guide will help you get up and running with our fullstack template quickly and efficiently.

Prerequisites

Required Tools

Node.js: Version 18.0.0 or higher
Python: Version 3.11 or higher
Docker: Latest version with Docker Compose
Git: Version control system
IDE: VS Code (recommended) or your preferred editor

Recommended VS Code Extensions

{
  "recommendations": [
    "esbenp.prettier-vscode",
    "dbaeumer.vscode-eslint",
    "@bradlc/vscode-tailwindcss",
    "ms-python.python",
    "ms-python.flake8",
    "ms-vscode.vscode-typescript-next",
    "bradlc.vscode-tailwindcss",
    "formulahendry.auto-rename-tag",
    "christian-kohler.path-intellisense"
  ]
}

Getting Started

1. Clone and Setup

# Clone the repository
git clone https://github.com/[your-org]/fullstack-template.git
cd fullstack-template

# Install dependencies
make install

# Copy environment files
cp .env.example .env
cp frontend/.env.example frontend/.env.local
cp backend/.env.example backend/.env

2. Environment Configuration

Update the following files with your local settings:

`.env` (Root)

# Database
DATABASE_URL=postgresql://postgres:password@localhost:5432/fullstack_db

# Redis
REDIS_URL=redis://localhost:6379

# Environment
NODE_ENV=development
ENVIRONMENT=development

`frontend/.env.local`

NEXT_PUBLIC_API_URL=http://localhost:8000
NEXT_PUBLIC_APP_URL=http://localhost:3000

`backend/.env`

DATABASE_URL=postgresql://postgres:password@localhost:5432/fullstack_db
REDIS_URL=redis://localhost:6379
DEBUG=true
CORS_ORIGINS=http://localhost:3000

3. Start Development Environment

# Start all services
make dev

# Or start services individually
make dev-backend  # Backend only
make dev-frontend # Frontend only

4. Verify Setup

Frontend: http://localhost:3000
Backend API: http://localhost:8000/api/docs
Database: Check connection via API health endpoint

Project Structure

fullstack-template/
├── frontend/               # Next.js application
│   ├── src/
│   │   ├── app/           # App router pages
│   │   ├── components/    # Reusable components
│   │   ├── hooks/         # Custom React hooks
│   │   ├── lib/           # Utility libraries
│   │   └── types/         # TypeScript type definitions
│   ├── public/            # Static assets
│   └── package.json
├── backend/               # FastAPI application
│   ├── app/
│   │   ├── api/           # API endpoints
│   │   ├── core/          # Core functionality
│   │   ├── models/        # Database models
│   │   └── main.py        # Application entry point
│   └── requirements.txt
├── docs/                  # Documentation
└── Makefile              # Development commands

Development Workflow

1. Branch Management

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes and commit
git add .
git commit -m "feat: add new feature"

# Push and create PR
git push origin feature/your-feature-name

2. Code Quality

# Run linting
make lint

# Run tests
make test

# Run type checking
make type-check

# Format code
make format

3. Database Changes

# Create migration
cd backend
alembic revision --autogenerate -m "Add new table"

# Apply migration
alembic upgrade head

# Rollback if needed
alembic downgrade -1

Common Tasks

Adding New API Endpoint

Create endpoint in backend/app/api/endpoints/
Add route to backend/app/api/api.py
Create tests in tests/api/
Update API documentation

Adding New React Component

Create component in frontend/src/components/
Add to component index file
Create tests in __tests__/
Add Storybook story if applicable

Environment Variables

Add to .env.example files
Update environment configuration docs
Add validation in config files
Update deployment scripts

Troubleshooting

Common Issues

Port Already in Use

# Find process using port
lsof -ti:3000
lsof -ti:8000

# Kill process
kill -9 [PID]

Database Connection Issues

# Reset database
make db-reset

# Check Docker containers
docker-compose ps

# View logs
docker-compose logs postgres

Module Not Found Errors

# Clear node modules and reinstall
rm -rf frontend/node_modules
cd frontend && npm install

# Clear Python cache
find . -name "*.pyc" -delete
find . -name "__pycache__" -type d -exec rm -rf {} +

Docker Issues

# Reset Docker environment
make clean
docker system prune -af

# Rebuild containers
docker-compose build --no-cache

Development Standards

Code Style

Frontend: ESLint + Prettier configuration
Backend: Black + isort + flake8
Commits: Conventional Commits format
Naming: camelCase (JS/TS), snake_case (Python)

Testing Requirements

Unit Tests: Required for all business logic
Integration Tests: Required for API endpoints
E2E Tests: Required for critical user flows
Coverage: Minimum 80% for new code

Documentation

README: Update for new features
API Docs: Auto-generated with OpenAPI
Code Comments: For complex business logic
Architecture Decisions: Document in ADR format

Getting Help

Internal Resources

Team Chat: #development channel
Code Reviews: Required for all PRs
Office Hours: Daily 2-3 PM EST
Documentation: This docs folder

External Resources

Next.js Docs: https://nextjs.org/docs
FastAPI Docs: https://fastapi.tiangolo.com/
React Docs: https://react.dev/
TypeScript Docs: https://www.typescriptlang.org/docs/

Your First Contribution

Suggested First Tasks

Fix a small bug - Look for good-first-issue labels
Update documentation - Improve this onboarding guide
Add tests - Increase test coverage
Refactor component - Improve code quality

Checklist for First PR

Next Steps

Complete setup verification - Ensure all services are running
Review codebase - Explore existing code structure
Read architecture docs - Understand system design
Join team meetings - Daily standups and planning
Pick first task - Start with something small

Feedback

This onboarding guide is a living document. Please submit improvements via:

GitHub Issues: For bugs or missing information
Pull Requests: For direct improvements
Team Feedback: During retrospectives

Welcome to the team! 🎉

FilesExpand file tree

developer-onboarding.md

Latest commit

History