MacPro Mako - Codebase Analysis & Setup Guide
Table of Contents
- Project Overview
- Architecture Overview
- Technology Stack
- Key Concepts Explained
- Project Structure
- Local Development Setup
- AWS Deployment Setup
- Development Workflow
- Testing Strategy
- Troubleshooting
Project Overview
MacPro Mako is a full-stack web application built with modern TypeScript/Node.js technologies.
It's a government healthcare application that appears to handle form submissions, user management, and data
processing for various healthcare-related forms (ABP, CS, ER, G series forms).
The application consists of:
- Frontend: React-based web application with modern UI components
- Backend: AWS Lambda functions with API Gateway
- Infrastructure: AWS CDK for infrastructure as code
- Database: OpenSearch for data storage and search
- Authentication: AWS Cognito with optional IDM integration
Architecture Overview
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ React App │ │ API Gateway │ │ Lambda │
│ (Frontend) │◄──►│ (REST API) │◄──►│ Functions │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ CloudFront │ │ Cognito │ │ OpenSearch │
│ (CDN) │ │ (Auth) │ │ (Database) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Technology Stack
Frontend Technologies
- React 18: Modern React with hooks and functional components
- TypeScript: Type-safe JavaScript development
- Vite: Fast build tool and development server
- Tailwind CSS: Utility-first CSS framework
- Radix UI: Accessible UI component primitives
- React Hook Form: Form handling with validation
- React Query (TanStack Query): Server state management
- React Router: Client-side routing
- Framer Motion: Animation library
Backend Technologies
- AWS Lambda: Serverless compute functions
- AWS API Gateway: REST API management
- AWS Cognito: User authentication and authorization
- OpenSearch: Search and analytics engine
- AWS S3: File storage for attachments
- AWS SQS: Message queuing
- AWS Secrets Manager: Secure configuration management
Infrastructure & DevOps
- AWS CDK: Infrastructure as Code (TypeScript)
- Bun: Fast JavaScript runtime and package manager
- Turbo: Monorepo build system
- Vitest: Unit testing framework
- Playwright: End-to-end testing
- ESLint + Prettier: Code linting and formatting
Additional Tools
- LaunchDarkly: Feature flag management
- Google Analytics: User analytics
- MSW (Mock Service Worker): API mocking for development
Key Concepts Explained
1. Monorepo Architecture
The project uses a monorepo structure where multiple related projects are managed in a single
repository:
```
macpro-mako/
├── lib/ # Backend infrastructure and libraries
├── react-app/ # Frontend React application
├── bin/ # CLI tools and CDK entry point
├── test/ # End-to-end tests
└── mocks/ # Mock data and services
Benefits:
- Shared code and types between frontend and backend
- Consistent tooling and dependencies
- Easier coordination between teams
- Single source of truth for the entire application
2. Infrastructure as Code (IaC)
The project uses AWS CDK to define infrastructure using TypeScript:
```
// Example from lib/stacks/parent.ts
new Stacks.Api(this, "api", {
project: props.project,
stage: props.stage,
vpc,
privateSubnets,
// ... other configuration
});
Benefits:
- Version-controlled infrastructure
- Type-safe infrastructure definitions
- Automated deployment and rollback
- Consistent environments across stages
3. Serverless Architecture
The backend uses AWS Lambda functions for serverless compute:
- No server management: AWS handles scaling and maintenance
- Pay-per-use: Only pay for actual compute time
- Auto-scaling: Automatically scales based on demand
- Event-driven: Functions triggered by API calls, SQS messages, etc.
4. Type Safety
The entire project uses TypeScript for type safety:
```
// Shared types between frontend and backend
export interface User {
id: string;
email: string;
role: UserRole;
}
Benefits:
- Catch errors at compile time
- Better IDE support and autocomplete
- Self-documenting code
- Refactoring safety
5. Feature Flags
Uses LaunchDarkly for feature flag management:
```
const loginFlag = useFeatureFlag("LOGIN_PAGE");
Benefits:
- Gradual feature rollouts
- A/B testing capabilities
- Emergency feature toggles
- Environment-specific features
Project Structure
Core Directories
/lib - Backend Infrastructure
/stacks/: AWS CDK stack definitions/lambda/: AWS Lambda function code/config/: Configuration management/packages/: Shared libraries and utilities/local-constructs/: Custom CDK constructs
/react-app - Frontend Application
/src/components/: Reusable UI components/src/features/: Feature-based organization/src/hooks/: Custom React hooks/src/utils/: Utility functions/src/api/: API client code
/bin - CLI and Tools
/cli/: Command-line interface toolsapp.ts: CDK application entry point
/test - Testing
/e2e/: End-to-end tests with Playwright/fixtures/: Test data and utilities
Local Development Setup
Prerequisites
- Node.js (v18 or higher)
- Bun (v1.1.20 or higher) - Fast JavaScript runtime
- AWS CLI configured with appropriate credentials
- Docker (for some local services)
Installation Steps
-
Clone the repository:
```
git clone
cd macpro-mako
-
Install dependencies:
```
# Install Bun if not already installed
curl -fsSL https://bun.sh/install | bash
# Install project dependencies
bun install
-
Set up environment variables:
```
# Copy example environment file
cp .env.example .env
# Edit with your local configuration
nano .env
-
Start development servers:
```
# Start frontend development server
bun run bun:dev
# Start backend services (if needed)
bun run cdk:watch
Development Commands
```
# Build the project
bun run build
# Run tests
bun run test
# Run end-to-end tests
bun run e2e
# Lint code
bun run lint
# Format code
bun run format:write
# Type checking
bun run test-tsc
AWS Deployment Setup
Prerequisites
- AWS Account with appropriate permissions
- AWS CLI configured
- AWS CDK installed globally
- Domain name (for production)
Deployment Steps
-
Configure AWS credentials:
```
aws configure
-
Bootstrap CDK (first time only):
```
cdk bootstrap
-
Set up secrets in AWS Secrets Manager:
```
# Create project-default secret
aws secretsmanager create-secret \
--name "your-project-default" \
--secret-string '{"brokerString":"...","dbInfoSecretName":"..."}'
# Create stage-specific secret
aws secretsmanager create-secret \
--name "your-project-local" \
--secret-string '{"stage":"local"}'
-
Deploy to a specific stage:
```
# Deploy to local stage
cdk deploy -c stage=local
# Deploy to production
cdk deploy -c stage=production
Environment Variables Required
```
# Required for deployment
export PROJECT="your-project-name"
export REGION_A="us-east-1"
export CDK_DEFAULT_ACCOUNT="your-aws-account-id"
export CDK_DEFAULT_REGION="us-east-1"
# Optional for development
export STAGE="local"
Infrastructure Components Deployed
- Networking Stack: VPC, subnets, security groups
- API Stack: API Gateway, Lambda functions
- Auth Stack: Cognito user pools and identity pools
- Data Stack: OpenSearch domain, S3 buckets
- UI Stack: CloudFront distribution, S3 hosting
- Email Stack: Email processing Lambda functions
- Alerts Stack: SNS topics for notifications
Development Workflow
1. Feature Development
```
# Create a new feature branch
git checkout -b feature/new-feature
# Make changes and test locally
bun run test
bun run e2e
# Commit changes
git add .
git commit -m "feat: add new feature"
# Push and create pull request
git push origin feature/new-feature
2. Code Quality
The project enforces code quality through:
- ESLint: Code linting and style enforcement
- Prettier: Code formatting
- TypeScript: Type checking
- Vitest: Unit testing
- Playwright: End-to-end testing
3. Deployment Pipeline
```
# Deploy to development
cdk deploy -c stage=dev
# Deploy to validation
cdk deploy -c stage=val
# Deploy to production
cdk deploy -c stage=production
Testing Strategy
1. Unit Tests (Vitest)
```
# Run all unit tests
bun run test
# Run tests with coverage
bun run test:coverage
# Run tests in watch mode
bun run test:ui
2. End-to-End Tests (Playwright)
```
# Run all E2E tests
bun run e2e
# Run E2E tests with UI
bun run e2e:ui
3. Type Checking
```
# Check TypeScript types
bun run test-tsc
Troubleshooting
Common Issues
-
Bun installation issues:
```
# Reinstall Bun
curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
-
CDK deployment failures:
```
# Check AWS credentials
aws sts get-caller-identity
# Bootstrap CDK
cdk bootstrap
-
TypeScript errors:
```
# Clear TypeScript cache
rm -rf node_modules/.cache
bun install
-
Test failures:
```
# Clear test cache
rm -rf node_modules/.cache
bun run test --reporter=verbose
Getting Help
- Check the project's GitHub issues
- Review AWS CDK documentation
- Check TypeScript and React documentation
- Review the project's internal documentation
Additional Resources
📚 Documentation Files
🎯 Start Here
This documentation provides a comprehensive overview of the MacPro Mako codebase. For specific implementation
details, refer to the individual source files and their inline documentation.