DeliverU Developer Notes

Welcome to the DeliverU development documentation! This folder contains comprehensive notes about the system architecture, workflows, and development practices. Whether you're a new team member or an existing developer, these notes will help you understand and navigate the codebase effectively.

📚 Documentation Structure

🏗️ Architecture & Infrastructure

• System Overview - High-level architecture and technology stack
• Monorepo Structure - Understanding the workspace organization
• Infrastructure (CDK) - AWS CDK setup, stages, and deployment
• Infrastructure (Terraform) - Terraform configuration and usage
• Database Architecture - PostgreSQL, Drizzle ORM, and data models
• Event-Driven Architecture - AWS EventBridge and Restate workflows

💻 Applications

• WebApp (Main Application) - Main user-facing application
• JobBoard Application - Job board application
• JobWebsite Application - Public job website

📦 Packages & Libraries

• Core Package - Shared business logic and domain models
• Functions Package - Serverless Lambda functions
• UI Package - Shared UI components
• Templates Package - Email and document templates
• Storybook - UI component development and testing
• Tests Package - Testing infrastructure and strategies
• Langfuse Package - AI prompt management

🔧 Development Workflows

• Getting Started - Setting up your local environment
• Database Migrations - Creating and managing database changes
• Writing Actions - Form submissions and action handlers
• Testing Strategy - Unit, integration, and E2E testing
• CI/CD Pipeline - GitHub Actions workflows
• Deployment Process - Staging and production deployments
• Code Review Guidelines - PR review checklist and standards

🔌 Integrations

• Authentication (Clerk) - User authentication and authorization
• Google Maps & Places - Location services integration
• Google Vertex AI - AI/ML capabilities
• AWS Services - S3, Lambda, EventBridge
• Unipile Integration - Third-party integration
• Analytics (PostHog) - Product analytics and feature flags

📝 Best Practices

• Code Standards - TypeScript, React, and coding conventions
• Error Handling - Error management patterns
• Performance Guidelines - Optimization best practices
• Security Guidelines - Security best practices
• Accessibility - A11y standards and testing

🚨 Troubleshooting

• Common Issues - Frequently encountered problems and solutions
• Debugging Guide - Tools and techniques
• Infrastructure Issues - AWS, CDK, and deployment problems

📋 Reference

• Environment Variables - All environment variables and secrets
• Scripts Reference - Available npm/pnpm scripts
• API Endpoints - API documentation
• Database Schema - Tables, relationships, and indexes
• Glossary - Terms and acronyms

🎯 Quick Start Paths

New Developer Onboarding (Read in order)

1. System Overview
2. Monorepo Structure
3. Getting Started
4. WebApp Application
5. Code Standards

Infrastructure Changes

1. Infrastructure (CDK)
2. Deployment Process
3. Infrastructure Issues

Database Work

1. Database Architecture
2. Database Migrations
3. Database Schema Reference

Feature Development

1. Writing Actions
2. Testing Strategy
3. Code Review Guidelines

🔄 Keeping Notes Updated

This documentation should be a living document. When you make significant changes to the codebase:

1. Architecture Changes: Update relevant architecture docs
2. New Features: Document new patterns or integrations
3. Infrastructure Updates: Keep CDK/Terraform docs current
4. Process Changes: Update workflow documentation

📞 Getting Help

• Questions? Check Common Issues first
• Not Finding What You Need? Check the Glossary
• Still Stuck? Reach out to the team on Slack

📝 Contributing to Documentation

• Keep documentation close to the code it describes
• Use clear examples and code snippets
• Update docs when you update code
• Add diagrams where helpful (using Mermaid syntax)
• Follow the existing structure and format

---

Last Updated: December 2025 Maintainers: DeliverU Development Team