Developer Onboarding Guide

Source: This page is based on docs/ONBOARDING.md

Last Updated: January 20, 2026

This document provides a structured onboarding path for new developers joining the Eddy team. It balances comprehensive product understanding with practical development readiness, ensuring new team members can contribute effectively while understanding the broader context of what we're building.

Welcome to Eddy

Welcome! You're joining a team building something unique: a platform that transforms how organizations design, execute, and improve their business processes.

What Makes Eddy Different

We're not just a form builder or task manager - we're a game engine for work
We orchestrate complex, multi-person workflows with the same rigor that game engines orchestrate gameplay
We capture high-integrity data while providing process intelligence that helps organizations continuously improve

Our Values

Craftsmanship - We care deeply about code quality, architecture, and maintainability
Understanding over speed - We value deep comprehension over quick hacks
Documentation as a first-class citizen - We document extensively because it makes everyone more effective
Pragmatic problem-solving - We balance idealism with practical constraints

Onboarding Timeline

This onboarding is designed as a 4-week journey with clear milestones:

Week 1: Understand the product and technical foundations
Week 2: Set up your environment and make your first contribution
Weeks 3-4: Deep dives into specific areas and increasing autonomy

Important: This is a guide, not a rigid schedule. Some developers will move faster, others will need more time on certain areas. That's expected and okay.

Phase 1: Understanding Eddy (Days 1-3)

Goal: Understand what Eddy is, why it exists, and how it works from a user's perspective.

Day 1: Product Foundations

Morning: The Big Picture

Read: What is Eddy?
- This is your north star document
- Understand the "game engine for work" metaphor
- Grasp the three core arenas: Builder, Session, Sheet
Watch/Experience: Product Walkthrough
- Your manager will give you a live demo or recorded walkthrough
- See a workflow being built from scratch
- Watch a session being executed
- Explore a sheet with data

Afternoon: Hands-On Exploration

Create Your First Workflow
- Log into the staging environment
- Create a simple workflow (e.g., "Expense Approval")
- Add 2-3 pages with basic input blocks
- Create roles and assign them to pages
- Run through your workflow as different users

Deliverable: By end of day, you should be able to explain to a colleague: "What is Eddy and what problem does it solve?"

Day 2: Product Depth

Morning: The Three Arenas Deep Dive

The Builder

Read: Workflow Builder Architecture
- Understand the graph-based workflow design
- Learn about pages, sections, blocks, and transitions
- Grasp conditional logic and rules
Read: Block System Architecture
- Understand the building blocks of workflows
- Learn about different block types and their purposes

The Session

Read: Session Architecture
- Understand workflow runs (sessions)
- Learn about roles, assignments, and progression
- Grasp the state machine that powers sessions

The Sheet

Read: Sheet Architecture
- Understand how data flows from sessions to sheets
- Learn about the relationship between workflows and sheets
- Grasp the concept of structured data capture

Afternoon: Advanced Features

Explore Start Links: Read about self-service workflow starts
- Understand scheduled starts and self-service starts
- See how external users can initiate workflows
Explore Process Intelligence: Understand workflow metadata
- Understand how Eddy captures workflow metadata
- Learn about the analytics and insights we provide

Exercise: Build a more complex workflow with:

Multiple roles
Conditional transitions
A sheet section that displays data
A self-service start link

Day 3: Architecture & Philosophy

Morning: System Architecture

Read: Frontend App Map
- Understand the overall application structure
- Learn about the major components and their relationships
Read: API Endpoints (Skim, don't memorize)
- Get a sense of the API surface area
- Understand the domain organization
- Bookmark this for reference
Read: Database Schema (Skim the overview)
- Understand the core entities and their relationships
- Focus on: users, groups, workflows, workflow_runs, pages, blocks, sheets
- Bookmark this for reference

Afternoon: Development Philosophy

Read: Code Practice Guidelines
- Understand our code organization and conventions
- Learn our API endpoint patterns
- Understand our React and TypeScript best practices
Read: Development Principles
- Understand our development principles
- Learn what we value in developers
Read: AI Guidelines
- Understand our stance on AI-assisted development
- Learn how to use LLMs effectively and responsibly

Reflection Exercise: Write a short document (1-2 pages) answering:

What is Eddy's core value proposition?
What are the three main user experiences?
What makes Eddy's approach to workflows different from competitors?
Share this with your manager for discussion

Phase 2: Technical Foundation (Days 4-7)

Goal: Understand the technical stack, codebase structure, and development practices.

Day 4: Stack & Setup

Morning: Technology Stack

Review the Stack:

Frontend: Next.js (React), TypeScript, Zustand (state management)
Backend: Next.js API routes, Node.js
Database: PostgreSQL with Knex.js for queries and migrations
Authentication: Auth0
File Storage: UploadThing
Background Jobs: Inngest
Testing: Jest (unit/integration), Playwright (E2E)

Afternoon: Environment Setup

Set Up Your Development Environment:

Clone the repository
Install dependencies (npm install or yarn install)
Set up environment variables (.env.local)
Connect to the development database
Run the development server
Verify you can access the app locally

Verify Your Setup:

Create a test user account
Create a test workspace
Create a simple workflow
Confirm everything works

Checkpoint: You should have a fully functional local development environment.

Morning: Project Structure

Explore the Directory Structure:

/pages          - Next.js pages and API routes
/components     - React components
/services       - Business logic layer
/db             - Database connection
/migrations     - Database schema migrations
/types          - TypeScript type definitions
/util           - Utility functions
/hooks          - Custom React hooks
/store          - Zustand state management

Trace a Feature End-to-End:

Pick a simple feature (e.g., "Create a block")
Find the UI component (components/builder/)
Find the API endpoint (pages/api/blocks/create.ts)
Find the service layer (if applicable)
Find the database migration that created the table
Find the type definitions (types/block.ts)

Afternoon: Data Flow

Understand Data Fetching:

Learn how we use React Query for server state
Understand how hooks encapsulate API calls

Understand State Management:

Find examples of Zustand stores in /store
Understand when we use client state vs. server state

Exercise: Pick a component and trace its data flow:

What data does it need?
Where does it come from?
How is it fetched?
How is it updated?

Day 6: Database & Migrations

Morning: Database Deep Dive

Read: Database Schema (Full read)
- Understand all core entities
- Understand the relationships between entities
- Pay special attention to the workflow hierarchy and sheet hierarchy
Explore Migrations:
- Look at recent migrations in /migrations
- Understand the migration naming convention
- Understand how to create a new migration
- Run npx knex migrate:latest to see migrations in action

Afternoon: Querying with Knex

Study Knex Patterns:

Find examples of Knex queries in API endpoints
Understand our patterns for:
- Simple selects
- Joins
- Transactions
- Soft deletes (archived_at)

Practice:

Write a simple query to fetch workflows for a group
Write a query to fetch all blocks for a page
Write a query with a join (e.g., workflow runs with user info)

Exercise: Create a new migration (don't run it, just practice):

Add a new column to an existing table
Follow the naming convention
Include both up and down migrations

Day 7: Testing & Quality

Morning: Testing Strategy

Read: Testing
- Understand our three-tier testing approach
- Learn about unit tests, integration tests, and E2E tests
Read: End-to-End Testing
- Understand our Playwright setup
- Learn about the createTestScenario helper
Run Tests:
- Run unit tests: npx jest __tests__/utils/
- Run integration tests: npx jest __tests__/integration/
- Run E2E tests: yarn e2e (or npx playwright test)

Afternoon: Code Quality

Explore Existing Tests:

Read a few unit tests in __tests__/utils/
Read an integration test in __tests__/integration/
Read an E2E test in __e2es__/

Write a Simple Test:

Pick a utility function
Write a unit test for it
Run the test and verify it passes

Checkpoint: You should understand how to run tests and write basic tests.

Phase 3: Development Environment & First Contribution (Days 8-14)

Goal: Make your first meaningful contribution to the codebase.

Days 8-9: First Bug Fix or Small Feature

Your First Ticket

Pick a Starter Task:

Your manager will assign you a "good first issue"
This should be a small, well-defined task
Examples:
- Fix a UI bug
- Add a missing validation
- Improve an error message
- Add a test for existing functionality

Work Through the Task:

Read the ticket carefully
Ask questions if anything is unclear
Plan your approach
Implement the solution
Write or update tests
Test manually in your local environment

Code Review Process:

Create a pull request
Respond to feedback
Learn from the review process

Key Learning: This is about learning our development workflow, not about the complexity of the code.

Days 10-14: Larger Feature or Refactor

A More Substantial Contribution

Pick a Medium-Sized Task:

Your manager will assign a task that requires:
- Understanding multiple parts of the codebase
- Making changes across frontend and backend
- Writing tests
Examples:
- Add a new block type
- Implement a new API endpoint
- Refactor a component to improve performance
- Add a new feature to the workflow builder

Plan Before Coding:

Discuss your approach with your manager or a senior developer
Identify what files you'll need to change
Identify what tests you'll need to write
Get feedback on your plan before implementing

Implement, Test, Review:

Follow the same process as your first task
Pay attention to code quality and conventions
Write comprehensive tests

Checkpoint: By the end of week 2, you should have made at least one merged contribution to the codebase.

Workflow Builder Architecture (re-read in detail)
Builder Audit
Workflow Validation
Block System Architecture

Code to Explore:

components/builder/ - All builder components
pages/api/workflows/, pages/api/pages/, pages/api/blocks/ - API endpoints
services/ - Workflow-related services

Exercise:

Build a complex workflow with all block types
Implement a new block type from scratch
Add a new validation rule to the workflow validator

Option B: Session Execution Deep Dive

Documents to Read:

Session Architecture (re-read in detail)
Session State Computation
Session Progression Rules
Assignments

Code to Explore:

components/session/ - Session components
pages/api/workflow_runs/, pages/api/session_assignments/ - API endpoints
Session state computation logic

Exercise:

Trace the complete lifecycle of a workflow run
Understand how assignments are created and managed
Understand how stage progression works

Option C: Sheets & Data Management Deep Dive

Documents to Read:

Sheet Architecture (re-read in detail)
Sheets Audit
Sheet Section Audit

Code to Explore:

components/sheet/ - Sheet components
components/sections/SheetSectionBody.tsx - Sheet section in sessions
pages/api/sheets/, pages/api/columns/, pages/api/rows/, pages/api/cells/ - API endpoints

Exercise:

Create a workflow that writes to multiple sheets
Implement a new column type
Build a complex sheet view with filters

Option D: Testing & Quality Assurance Deep Dive

Documents to Read:

Testing (re-read in detail)
End-to-End Testing

Code to Explore:

__tests__/ - All test files
__e2es__/ - E2E test files

Exercise:

Write comprehensive tests for an untested feature
Create a new E2E test for a critical user flow
Improve test coverage for a specific area

Week 4: Autonomy & Ownership

By week 4, you should be:

Taking on tickets independently
Participating in code reviews
Contributing to technical discussions
Identifying areas for improvement
Asking thoughtful questions

Development environment configured
IDE set up with recommended extensions
Git configured with correct email
SSH keys set up
VPN configured (if applicable)

Documentation

Read all Phase 1 documents
Bookmarked key reference documents
Added to team documentation repository

Ongoing Learning & Resources

Regular Reading

Code review comments on PRs
Team technical discussions in Slack
Architecture decision records (ADRs)
This documentation (it evolves!)

Recommended Resources

The Pragmatic Programmer
Designing Data-Intensive Applications
Next.js documentation
React documentation
PostgreSQL documentation

Getting Help

When You're Stuck

Try to solve it yourself first (15-30 minutes)
- Read the code
- Check the documentation
- Search Slack history
Ask for help (don't stay stuck!)
- Post in the team Slack channel
- Tag relevant team members
- Share what you've tried
Pair programming
- Schedule time with a senior developer
- Screen share and work through the problem together

Questions Are Welcome

There are no stupid questions
Asking questions helps improve our documentation
Your fresh perspective is valuable

Welcome to the team! We're excited to have you building Eddy with us.

Developer Onboarding

On this page