Developer Onboarding

A structured learning path for new developers joining the Vertical Template project.

Day 1: Environment Setup (30 minutes)

Morning: Get Running

1. Setup Environment (15 minutes)

   • Complete Prerequisites
   • Follow Quickstart
   • Verify app runs at localhost:3000

2. Explore the Codebase (15 minutes)

   • Browse src/ folder structure
   • Open src/eai.config/tenants/template.config.ts
   • Look at src/app/page.tsx

Afternoon: First Modification

3. Your First Change (30 minutes)
   • Complete First Vertical tutorial
   • Create a tenant config with your name
   • Add one custom component

Day 1 Checkpoint:

• App runs locally without errors
• Can explain what a "tenant config" is
• Made at least one code change and saw hot reload

---

Day 2: Understanding Architecture (1 hour)

Morning: System Architecture

1. Read Architecture Docs (30 minutes)

   • Architecture Overview
   • Project Structure
   • Focus on the BFF proxy pattern

2. Trace a Request (15 minutes)

   • Open browser DevTools → Network tab
   • Click around in the app
   • Find calls to /api/eai/*
   • Understand: Browser → Next.js → Backend

Afternoon: Configuration System

3. Deep Dive: Config System (30 minutes)

   • Read Configuration Overview
   • Study src/eai.config/types.ts
   • Understand store slices, layout slots, storeBindings

4. Experiment (15 minutes)

   • Modify a showWhen condition
   • Add a new store slice
   • Change component priority order

Day 2 Checkpoint:

• Can draw the request flow (Browser → BFF → Backend)
• Understand config-driven UI concept
• Can explain store slices and storeBindings

---

Week 1: Building Features

Days 3-4: Extension Patterns

1. Adding Pages (1 hour)

   • Read Adding Pages
   • Create a new page at /dashboard
   • Make it tenant-aware

2. Adding API Routes (1 hour)

   • Read Adding API Routes
   • Create a protected API endpoint
   • Use the withAuth middleware

3. Custom Components (1 hour)

   • Read Custom Components
   • Create a component using Shadcn/ui primitives
   • Register it in ComponentRegistry
   • Add to a tenant config

Day 5: State Management

4. Zustand Store Patterns (1 hour)
   • Read Data Flow
   • Use useStoreValue, useSetStore
   • Implement slice persistence
   • Debug with Redux DevTools

Week 1 Checkpoint:

• Created a new page
• Created a protected API route
• Created and registered a custom component
• Used store hooks to read/write state

---

Week 2: Advanced Topics

API Integration

1. Client Package (2 hours)

   • Explore packages/client/
   • Use useProjects, useProvision hooks
   • Understand createAPIClient factory

2. Public API Access (1 hour)

   • Read Public API Access
   • Understand Client Credentials Flow
   • Create a public endpoint

Architecture Decisions

3. ADRs (1 hour)
   • Read ADRs in docs/architecture/decisions/
   • Understand "why" behind technical choices
   • Learn when to create new ADRs

AI-Assisted Development

4. CLAUDE.md and Skills (30 minutes)
   • Read CLAUDE.md at project root
   • Understand AI context files
   • Try Agent Skills (if using Claude Code)

Week 2 Checkpoint:

• Made API calls using client hooks
• Understand authentication flows
• Know where to find architectural decisions
• Comfortable with AI assistance tools

---

Reference Reading List

Required Reading (First Week)

Document	Time	Purpose
Quickstart	10 min	Get running
First Vertical	30 min	Hands-on learning
Architecture Overview	20 min	System understanding
Configuration Overview	20 min	Config system

Recommended Reading (First Month)

Document	Time	Purpose
Tenant Config Reference	30 min	Deep config knowledge
All ADRs	45 min	Architectural context
Hooks Reference	30 min	API reference
Components Reference	30 min	Component catalog

External Resources

• Next.js App Router Docs
• Zustand Documentation
• Auth.js (NextAuth) Guide
• Tailwind CSS Docs
• Shadcn/ui Components

---

Getting Help

Internal Resources

• GitHub Issues: Report bugs or request features
• CLAUDE.md: AI-optimized project context

Asking Good Questions

When seeking help, include:

1. What you're trying to accomplish
2. What you've tried
3. Error messages (full text)
4. Relevant code snippets

Common Stumbling Blocks

Issue	Usually Caused By	Solution
Component not rendering	Not in ComponentRegistry	Register component
Store not updating	Wrong storePath	Check path in config
API 401 errors	Missing/expired token	Check Entra credentials
Type errors	Outdated deps	npm install

---

Onboarding Completion Checklist

By the end of Week 2, you should be able to:

• Set up local development environment
• Create new tenant configurations
• Add pages, API routes, and components
• Use the Zustand store effectively
• Make authenticated API calls
• Navigate codebase independently
• Understand architecture decisions
• Find answers in documentation

Welcome to the team! 🎉