Quick Reference Guide - MacPro Mako

Essential Technologies & Concepts

🚀 Core Technologies

Technology	Purpose	Key Files
TypeScript	Type-safe JavaScript	`tsconfig.json`, `.ts`, `.tsx`
React 18	Frontend UI framework	`react-app/src/`
AWS CDK	Infrastructure as Code	`lib/stacks/`, `bin/app.ts`
AWS Lambda	Serverless functions	`lib/lambda/`
Bun	Package manager & runtime	`bunfig.toml`, `package.json`
Vite	Build tool & dev server	`react-app/vite.config.ts`

🏗️ Architecture Patterns

Monorepo Structure

``` macpro-mako/ ├── lib/ # Backend & Infrastructure ├── react-app/ # Frontend Application ├── bin/ # CLI & CDK Entry ├── test/ # E2E Tests └── mocks/ # Mock Services ```

AWS Services Used

API Gateway → REST API endpoints
Lambda → Serverless compute
Cognito → Authentication
OpenSearch → Database & Search
S3 → File storage
CloudFront → CDN
SQS → Message queuing
Secrets Manager → Configuration

📦 Package Management

Bun (Primary Package Manager)

# Install dependencies
bun install

# Run scripts
bun run <script-name>

# Add new package
bun add <package-name>

# Add dev dependency
bun add -d <package-name>

Key Scripts

bun run build          # Build all packages
bun run test           # Run unit tests
bun run e2e            # Run E2E tests
bun run lint           # Lint code
bun run format:write   # Format code
bun run cdk deploy     # Deploy to AWS

🔧 Development Tools

TypeScript Configuration

Target: esnext
Module: esnext
JSX: react-jsx
Strict mode: Enabled
Path mapping: Configured for monorepo

Testing Stack

Vitest: Unit testing
Playwright: E2E testing
MSW: API mocking
Happy DOM: DOM testing environment

Code Quality

ESLint: Code linting
Prettier: Code formatting
TypeScript: Type checking
Turbo: Build orchestration

🌐 Frontend Stack

React Ecosystem

// Key libraries
import React from 'react'
import { QueryClient } from '@tanstack/react-query'
import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'

UI Components

Radix UI: Accessible primitives
Tailwind CSS: Utility-first styling
Framer Motion: Animations
Heroicons: Icons

State Management

React Query: Server state
React Hook Form: Form state
React Context: Global state (if needed)

☁️ AWS Infrastructure

CDK Stacks

// Main stacks defined in lib/stacks/
- NetworkingStack    // VPC, subnets, security groups
- ApiStack           // API Gateway, Lambda functions
- AuthStack          // Cognito user pools
- DataStack          // OpenSearch, S3
- UiInfraStack       // CloudFront, S3 hosting
- EmailStack         // Email processing
- AlertsStack        // SNS notifications

Deployment Stages

# Development stages
local → dev → val → production

# Deploy command
cdk deploy -c stage=<stage-name>

🔐 Authentication & Security

Cognito Integration

User Pools: User registration/login
Identity Pools: AWS resource access
IDM Integration: Optional enterprise auth

Security Features

IAM Permissions Boundary: Resource access control
IAM Path: Organization structure
Secrets Manager: Secure configuration
VPC: Network isolation

📊 Data & Storage

OpenSearch (Elasticsearch)

Primary database for application data
Search functionality across documents
Analytics and reporting

S3 Storage

File attachments for forms
Static assets for frontend
Backup and archival

🔄 Development Workflow

1. Local Development

# Start frontend
bun run bun:dev

# Start backend (if needed)
bun run cdk:watch

# Run tests
bun run test

2. Code Changes

# Create feature branch
git checkout -b feature/new-feature

# Make changes and test
bun run test
bun run e2e

# Commit and push
git add .
git commit -m "feat: add new feature"
git push origin feature/new-feature

3. Deployment

# Deploy to development
cdk deploy -c stage=dev

# Deploy to production
cdk deploy -c stage=production

🛠️ Common Commands

Development

# Install dependencies
bun install

# Start development server
bun run bun:dev

# Run tests
bun run test

# Type checking
bun run test-tsc

# Lint code
bun run lint

# Format code
bun run format:write

AWS/CDK

# Bootstrap CDK (first time)
cdk bootstrap

# Deploy infrastructure
cdk deploy -c stage=local

# Watch for changes
cdk watch -c stage=local

# Destroy infrastructure
cdk destroy -c stage=local

Testing

# Unit tests
bun run test

# E2E tests
bun run e2e

# Test with UI
bun run test:ui

# Coverage report
bun run test:coverage

📁 Key File Locations

File	Purpose
`package.json`	Root dependencies & scripts
`cdk.json`	CDK configuration
`tsconfig.json`	TypeScript configuration
`turbo.json`	Monorepo build configuration
`bunfig.toml`	Bun configuration
`react-app/vite.config.ts`	Frontend build configuration
`lib/stacks/parent.ts`	Main CDK stack
`bin/app.ts`	CDK application entry point

🔍 Environment Variables

Required for Deployment

PROJECT="your-project-name"
REGION_A="us-east-1"
CDK_DEFAULT_ACCOUNT="your-aws-account-id"
CDK_DEFAULT_REGION="us-east-1"

Optional for Development

STAGE="local"
AWS_ACCESS_KEY_ID="your-access-key"
AWS_SECRET_ACCESS_KEY="your-secret-key"

🚨 Troubleshooting

Common Issues

Bun not found: Install with curl -fsSL https://bun.sh/install | bash
CDK errors: Run cdk bootstrap first
TypeScript errors: Clear cache with rm -rf node_modules/.cache
Test failures: Check environment variables and AWS credentials

Getting Help

Check project documentation
Review AWS CDK docs
Check TypeScript/React documentation
Look at existing code examples in the project

This quick reference covers the essential concepts and commands you'll need to work with the MacPro Mako codebase. For detailed explanations, refer to the main README.md file.