Development Workflow

This guide explains the development workflow for contributing to Plus261. Follow these steps to ensure quality code and smooth collaboration.

New Developer?

If you’re new to the project, start with the Quick Start Guide to get set up, then return here to learn the workflow.

What You’ll Learn

By the end of this guide, you’ll understand:

• ✅ The complete development workflow
• ✅ How to create feature branches
• ✅ How to write and test code
• ✅ How to commit and submit changes
• ✅ Best practices for code quality
• ✅ Common development tasks

Overview

The development workflow follows these steps:

1. Setup - Configure your environment
2. Planning - Understand requirements
3. Development - Write code following conventions
4. Testing - Write and run tests
5. Review - Submit for code review
6. Deploy - Merge and deploy

Development Workflow

Step 1: Setup Your Environment

See Quick Start for initial setup.

Quick Checklist:

• bun install at repo root

• bun --bun run k8s:up succeeded (default: K8S_PROFILE=core)

• /etc/hosts includes at least api.plus261.local (more hosts for core / full)

• kubectl -n plus261-app get pods shows Ready (postgres, redis, api, worker)

• https://api.plus261.local/live and https://api.plus261.local/ready return 200

• https://api.plus261.local/graphql opens

• ✅ Repository cloned

• ✅ Dependencies installed (bun install)

• ✅ Cluster running (bun --bun run k8s:up / kubectl -n plus261-app get pods)

• ✅ /etc/hosts configured for enabled *.local hosts

• ✅ Migrations applied when needed — see Migrations Drizzle

Step 2: Create a Feature Branch

# Update main branch
git checkout main
git pull origin main

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

# Or for bug fixes
git checkout -b fix/your-bug-description

Branch prefixes mirror Conventional Commits types (feat/, fix/, docs/, …).

Step 3: Develop Your Feature

Understand the Requirements

Before coding:

• ✅ Read the issue or specification carefully
• ✅ Understand the business logic
• ✅ Check existing similar features for patterns
• ✅ Ask questions if unclear

Write Code

Follow these principles:

1. Start Small - Make incremental changes
2. Follow Conventions - See Code Style
3. Use Existing Patterns - Look at similar modules
4. Write Tests - See Testing Guide

Example: Adding a New Module

# 1. Create module structure
mkdir -p apps/api/src/new-module/dto

# 2. Create DTOs (see Code Structure guide)
# 3. Create module configuration
# 4. Register in create-schema.ts
# 5. Write tests

Detailed Guide: Code Structure - Creating a New Module

Web frontend with SSO

bun --bun run k8s:up
bun --bun run k8s:hotreload -- web soacaille   # http://127.0.0.1:3003

Guide : Getting started.

Step 4: Test Your Changes

# Run tests
bun test

# Code quality (monorepo root)
bun --bun run check:code

# Svelte type-check (web, auth)
cd apps/web && bun --bun run check

Test Early

Run tests frequently during development to catch issues early.

Step 5: Commit Your Changes

Commit messages must follow Conventional Commits. Lefthook runs format + lint:fix before each commit and commitlint validates the message.

Full reference: Code Style — Commit messages (types, feat! breaking changes, hooks).

Step 6: Push and Create Merge Request

# Push your branch
git push origin feat/your-feature-name

Then create a Merge Request on GitLab with:

• ✅ Clear title and description (Conventional Commits style recommended)
• ✅ Link to related issue
• ✅ Screenshots (if UI changes)
• ✅ Test results
• ✅ Checklist of changes

Step 7: Code Review

During code review:

• ✅ Address review comments promptly
• ✅ Make requested changes
• ✅ Keep discussions constructive
• ✅ Ask questions if unclear

Development Tools

VS Code Extensions (Recommended)

Extension	Purpose
oxlint (CLI)	Lint JS/TS (bun --bun run lint)
oxfmt (CLI)	Format (bun --bun run format)
TypeScript	Type checking
GraphQL	GraphQL syntax highlighting
Svelte	Svelte support

Useful Commands

# Development
bun dev              # Start development server
bun --bun run build        # Build for production
bun --bun run check:code   # lint:fix + format + lint (root)
cd apps/web && bun --bun run check   # Svelte/TS check

# Database
bunx drizzle-kit generate    # Generate migrations (from apps/api/)
bunx drizzle-kit migrate     # Run migrations — see /infrastructure/local-dev#migrations-drizzle-api
bunx drizzle-kit studio     # Open Drizzle Studio

# Testing
bun test             # Run tests
bun test:watch       # Watch mode

Best Practices

Code Quality

1. Write Clean Code

   • Follow Code Style
   • Keep functions small and focused
   • Use meaningful names
   • Add comments for complex logic

2. Handle Errors Properly

   • Use specific error types
   • Log errors appropriately
   • Provide helpful error messages
   • Don’t swallow errors silently

3. Document Complex Logic

   • Add JSDoc comments
   • Explain “why”, not “what”
   • Update documentation when code changes

Testing

1. Write Tests

   • Unit tests for business logic
   • Integration tests for API endpoints
   • Test edge cases
   • Test error scenarios

2. Test Coverage

   • Aim for good coverage
   • Focus on critical paths
   • Don’t test implementation details

Learn more: Testing Guide

Performance

1. Optimize Queries

   • Use DataLoaders for N+1 problems
   • Add database indexes
   • Use pagination
   • Cache frequently accessed data

2. Monitor Performance

   • Check query performance
   • Use observability tools
   • Profile slow operations

Learn more: Performance Guide

Common Development Tasks

Adding a New GraphQL Type

1. Create DTO in dto/type-name.type.ts
2. Add decorators (@ObjectType, @EnhancedField)
3. Create module configuration
4. Register in create-schema.ts

Guide: Code Structure - Creating a New Module

Adding a New Query

1. Use Type GraphQL Query auto-generated queries (recommended)
2. Or create custom resolver if needed
3. Add authorization if required
4. Write tests

Guide: Type GraphQL Query - Queries

Adding a New Mutation

1. Create input type in dto/type-name.input.ts
2. Configure in module
3. Add authorization
4. Test the mutation

Guide: Type GraphQL Query - Mutations

Modifying Database Schema

1. Update schema in libs/db/src/schema/
2. Generate migration: bunx drizzle-kit generate
3. Review migration file
4. Run migration: bunx drizzle-kit migrate

Data Loss

Always review migration files before running them. Some migrations may cause data loss.

Troubleshooting

Type Errors

# Clear caches and re-check
rm -rf node_modules/.cache
bun --bun run check:code
cd apps/web && bun --bun run check

Build Errors

# Clean and rebuild
bun --bun run clean
bun install
bun --bun run build

Database Issues

# Reset database (⚠️ deletes all data)
kubectl -n plus261-app delete pvc --all
bun --bun run k8s:deploy -- k3d
bunx drizzle-kit migrate

Port Already in Use

# Find process using port
lsof -i :4000

# Kill process
kill -9 <PID>

Quick Reference

Task	Documentation
Create a module	Code Structure
Add a query	Type GraphQL Query - Queries
Add a mutation	Type GraphQL Query - Mutations
Write tests	Testing Guide
Debug issues	Debugging Guide

Next Steps

Continue your learning:

1. 📚 Code Structure - Understand code organization
2. 🧪 Testing - Testing guidelines
3. 🐛 Debugging - Debugging techniques
4. 🤝 Contributing Guidelines - Contribution process

Related Topics

• Quick Start - Fast setup guide
• Code Structure - Codebase organization
• Code Style - Coding conventions
• Testing Guide - How to write tests