MacPro Mako - Code Structure & Technology Analysis
๐๏ธ Overall Architecture
MacPro Mako is a full-stack government healthcare application built with modern cloud-native
technologies. It follows a monorepo architecture with clear separation between frontend, backend,
and infrastructure components.
graph TB
subgraph "๐ Frontend Layer"
A[React App<br/>TypeScript + Vite] --> B[Components<br/>Radix UI + Tailwind]
A --> C[Features<br/>Dashboard, Forms, Auth]
A --> D[State Management<br/>React Query + Hook Form]
end
subgraph "โ๏ธ Backend Layer"
E[API Gateway<br/>REST Endpoints] --> F[Lambda Functions<br/>Serverless Compute]
F --> G[Business Logic<br/>Form Processing]
F --> H[Data Access<br/>OpenSearch + S3]
end
subgraph "๐ง Infrastructure Layer"
I[AWS CDK<br/>Infrastructure as Code] --> J[CloudFormation<br/>Resource Provisioning]
J --> K[VPC + Security<br/>Network Isolation]
J --> L[Authentication<br/>Cognito + IAM]
end
A -.->|HTTP Requests| E
F -.->|Data Operations| H
I -.->|Deploys| J
classDef frontend fill:#e1f5fe,stroke:#01579b,stroke-width:2px
classDef backend fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
classDef infra fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
class A,B,C,D frontend
class E,F,G,H backend
class I,J,K,L infra
๐ Project Structure Deep Dive
Root Level Organization
graph TD
subgraph "๐ฆ MacPro Mako Monorepo"
A[bin/] --> A1[CLI Tools<br/>CDK Entry Point]
B[lib/] --> B1[Backend Infrastructure<br/>Business Logic]
C[react-app/] --> C1[Frontend Application<br/>React + TypeScript]
D[test/] --> D1[E2E Tests<br/>Playwright]
E[mocks/] --> E1[Mock Services<br/>Testing Data]
F[package.json<br/>Root Dependencies]
G[cdk.json<br/>CDK Configuration]
H[tsconfig.json<br/>TypeScript Config]
I[turbo.json<br/>Build Orchestration]
J[bunfig.toml<br/>Bun Runtime Config]
end
classDef config fill:#fff3e0,stroke:#e65100,stroke-width:2px
classDef code fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
classDef test fill:#fce4ec,stroke:#c2185b,stroke-width:2px
class F,G,H,I,J config
class A,B,C code
class D,E test
1. Frontend Structure (react-app/)
graph TB
subgraph "๐จ React Application"
subgraph "๐ฑ Source Code"
A[src/] --> B[components/<br/>Reusable UI]
A --> C[features/<br/>Business Features]
A --> D[hooks/<br/>Custom Hooks]
A --> E[api/<br/>API Client]
A --> F[utils/<br/>Utilities]
A --> G[config.tsx<br/>App Configuration]
A --> H[main.tsx<br/>Entry Point]
A --> I[router.tsx<br/>Routing]
end
subgraph "๐๏ธ Build & Assets"
J[public/<br/>Static Assets]
K[package.json<br/>Dependencies]
L[vite.config.ts<br/>Build Config]
end
subgraph "๐ฏ Components"
B --> B1[ActionForm/<br/>Form Components]
B --> B2[Alert/<br/>Notifications]
B --> B3[Banner/<br/>Banners]
B --> B4[Cards/<br/>Layout Cards]
B --> B5[Form/<br/>Form Elements]
B --> B6[Inputs/<br/>Input Fields]
B --> B7[Layout/<br/>Page Layouts]
B --> B8[Profile/<br/>User Profiles]
B --> B9[RHF/<br/>React Hook Form]
B --> B10[Table/<br/>Data Tables]
end
subgraph "๐ Features"
C --> C1[dashboard/<br/>Dashboard]
C --> C2[forms/<br/>Form Handling]
C --> C3[login/<br/>Authentication]
C --> C4[profile/<br/>User Management]
C --> C5[webforms/<br/>Form Rendering]
end
end
classDef structure fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
classDef components fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
classDef features fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
classDef build fill:#fff3e0,stroke:#f57c00,stroke-width:2px
class A,J,K,L structure
class B,B1,B2,B3,B4,B5,B6,B7,B8,B9,B10 components
class C,C1,C2,C3,C4,C5 features
class D,E,F,G,H,I build
2. Backend Structure (lib/)
graph TB
subgraph "โ๏ธ Backend Infrastructure"
subgraph "๐๏ธ CDK Stacks"
A[stacks/] --> A1[parent.ts<br/>Main Orchestrator]
A --> A2[api.ts<br/>API Gateway + Lambda]
A --> A3[auth.ts<br/>Cognito Auth]
A --> A4[data.ts<br/>OpenSearch + S3]
A --> A5[networking.ts<br/>VPC + Security]
A --> A6[ui-infra.ts<br/>CloudFront + S3]
A --> A7[email.ts<br/>Email Processing]
A --> A8[alerts.ts<br/>SNS Notifications]
A --> A9[uploads.ts<br/>File Uploads]
end
subgraph "๐ง Lambda Functions"
B[lambda/] --> B1[search.ts<br/>OpenSearch Queries]
B --> B2[submit/<br/>Form Submissions]
B --> B3[update/<br/>Data Updates]
B --> B4[user-management/<br/>User Operations]
end
subgraph "โ๏ธ Configuration"
C[config/] --> C1[deployment-config.ts<br/>Environment Config]
C --> C2[bundling-config.ts<br/>Lambda Bundling]
end
subgraph "๐ฆ Shared Libraries"
D[packages/] --> D1[shared-types/<br/>TypeScript Types]
D --> D2[shared-utils/<br/>Utility Functions]
end
subgraph "๐จ Internal Libraries"
E[libs/] --> E1[api/<br/>API Utilities]
E --> E2[email/<br/>Email Processing]
E --> E3[webforms/<br/>Form Handling]
end
subgraph "๐๏ธ Custom Constructs"
F[local-constructs/<br/>Custom CDK Constructs]
end
end
classDef stacks fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
classDef lambda fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
classDef config fill:#fff3e0,stroke:#f57c00,stroke-width:2px
classDef shared fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
classDef libs fill:#fce4ec,stroke:#c2185b,stroke-width:2px
class A,A1,A2,A3,A4,A5,A6,A7,A8,A9 stacks
class B,B1,B2,B3,B4 lambda
class C,C1,C2 config
class D,D1,D2 shared
class E,E1,E2,E3,F libs
3. Infrastructure Stack Architecture
graph TB
subgraph "๐๏ธ CDK Stack Architecture"
subgraph "๐ฏ Parent Stack"
A[ParentStack<br/>Main Orchestrator] --> B[NetworkingStack<br/>VPC + Security]
A --> C[ApiStack<br/>API Gateway + Lambda]
A --> D[AuthStack<br/>Cognito + IAM]
A --> E[DataStack<br/>OpenSearch + S3]
A --> F[UiInfraStack<br/>CloudFront + S3]
A --> G[EmailStack<br/>Email Processing]
A --> H[AlertsStack<br/>SNS Notifications]
end
subgraph "๐ Dependencies"
B -.->|Security Groups| C
B -.->|VPC| D
B -.->|Private Subnets| E
C -.->|API Gateway| D
E -.->|OpenSearch Domain| C
F -.->|S3 Bucket| C
end
end
classDef parent fill:#e8f5e8,stroke:#2e7d32,stroke-width:3px
classDef stack fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
classDef deps fill:#fff3e0,stroke:#f57c00,stroke-width:1px,stroke-dasharray: 5 5
class A parent
class B,C,D,E,F,G,H stack
class deps deps
๐ Data Flow Architecture
Frontend to Backend Flow
sequenceDiagram
participant U as ๐ค User
participant R as ๐จ React App
participant AG as ๐ API Gateway
participant L as โก Lambda
participant OS as ๐ OpenSearch
participant S3 as ๐ฆ S3
U->>R: Interacts with form
R->>AG: HTTP Request
AG->>L: Invoke Lambda
L->>OS: Query data
OS-->>L: Return results
L->>S3: Upload files (if needed)
S3-->>L: Confirm upload
L-->>AG: JSON Response
AG-->>R: HTTP Response
R-->>U: Update UI
Note over R,OS: Authentication via Cognito JWT tokens
Note over L,S3: File uploads use presigned URLs
Authentication Flow
graph LR
subgraph "๐ Authentication Flow"
A[๐ค User Login] --> B[๐ Cognito User Pool]
B --> C[๐ซ JWT Token Generation]
C --> D[๐ API Gateway]
D --> E[๐ Lambda Authorization]
E --> F[โ
Protected Resources]
G[๐ Identity Pool] --> H[๐ AWS Resource Access]
end
C -.->|Token| D
E -.->|Validate| C
classDef user fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
classDef auth fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
classDef api fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
classDef resource fill:#fff3e0,stroke:#f57c00,stroke-width:2px
class A user
class B,C,G auth
class D,E api
class F,H resource
File Upload Flow
graph TB
subgraph "๐ File Upload Process"
A[๐ User File] --> B[๐ S3 Presigned URL]
B --> C[๐ฆ S3 Bucket Storage]
C --> D[โก Lambda Processing]
D --> E[๐ Metadata Indexing]
E --> F[๐ OpenSearch Document]
G[๐ Security] --> H[๐ก๏ธ Virus Scanning]
H --> I[๐ File Validation]
end
C -.->|Trigger| D
D -.->|Metadata| E
G -.->|Scan| C
classDef file fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
classDef storage fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
classDef process fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
classDef security fill:#fff3e0,stroke:#f57c00,stroke-width:2px
class A,B file
class C,F storage
class D,E process
class G,H,I security
๐ ๏ธ Technology Stack Visualization
Frontend Technology Stack
graph TB
subgraph "๐จ Frontend Technology Stack"
subgraph "โ๏ธ React Ecosystem"
A[React 18] --> A1[Functional Components]
A --> A2["Hooks (useState, useEffect)"]
A --> A3[Context API]
end
subgraph "๐ ๏ธ Build Tools"
B[Vite] --> B1[Fast Dev Server]
B --> B2[Hot Module Replacement]
B --> B3[TypeScript Compilation]
end
subgraph "๐ฏ State Management"
C[React Query] --> C1[Server State]
C --> C2[Caching]
C --> C3[Background Updates]
D[React Hook Form] --> D1[Form State]
D --> D2[Validation]
D --> D3[Performance]
end
subgraph "๐จ UI Framework"
E[Tailwind CSS] --> E1[Utility Classes]
E --> E2[Responsive Design]
F[Radix UI] --> F1[Accessible Components]
F --> F2[Headless UI]
G[Framer Motion] --> G1[Animations]
G --> G2[Transitions]
end
subgraph "๐ฃ๏ธ Routing"
H[React Router] --> H1[Client-side Routing]
H --> H2[Code Splitting]
H --> H3[Nested Routes]
end
end
classDef react fill:#61dafb,stroke:#282c34,stroke-width:2px
classDef build fill:#646cff,stroke:#535bf2,stroke-width:2px
classDef state fill:#ff6b6b,stroke:#ee5a52,stroke-width:2px
classDef ui fill:#4ecdc4,stroke:#44a08d,stroke-width:2px
classDef routing fill:#45b7d1,stroke:#96ceb4,stroke-width:2px
class A,A1,A2,A3 react
class B,B1,B2,B3 build
class C,C1,C2,C3,D,D1,D2,D3 state
class E,E1,E2,F,F1,F2,G,G1,G2 ui
class H,H1,H2,H3 routing
Backend Technology Stack
graph TB
subgraph "โ๏ธ Backend Technology Stack"
subgraph "โก Serverless"
A[AWS Lambda] --> A1[Event-driven]
A --> A2[Auto-scaling]
A --> A3[Pay-per-use]
end
subgraph "๐ API Management"
B[API Gateway] --> B1[REST Endpoints]
B --> B2[Request Routing]
B --> B3[Rate Limiting]
B --> B4[CORS Handling]
end
subgraph "๐ Authentication"
C[Cognito] --> C1[User Pools]
C --> C2[Identity Pools]
C --> C3[JWT Tokens]
C --> C4[OAuth Providers]
end
subgraph "๐พ Data Storage"
D[OpenSearch] --> D1[Document Storage]
D --> D2[Full-text Search]
D --> D3[Aggregations]
E[S3] --> E1[File Storage]
E --> E2[Static Assets]
E --> E3[Backup]
end
subgraph "๐จ Messaging"
F[SQS] --> F1[Message Queuing]
F --> F2[Async Processing]
G[SNS] --> G1[Notifications]
G --> G2[Event Publishing]
end
end
classDef serverless fill:#ff9900,stroke:#232f3e,stroke-width:2px
classDef api fill:#00a1f1,stroke:#232f3e,stroke-width:2px
classDef auth fill:#ff6b6b,stroke:#ee5a52,stroke-width:2px
classDef storage fill:#00d4aa,stroke:#232f3e,stroke-width:2px
classDef messaging fill:#ff6b35,stroke:#f7931e,stroke-width:2px
class A,A1,A2,A3 serverless
class B,B1,B2,B3,B4 api
class C,C1,C2,C3,C4 auth
class D,D1,D2,D3,E,E1,E2,E3 storage
class F,F1,F2,G,G1,G2 messaging
Infrastructure Technology Stack
graph TB
subgraph "๐๏ธ Infrastructure Technology Stack"
subgraph "๐ Infrastructure as Code"
A[AWS CDK] --> A1[TypeScript DSL]
A --> A2[CloudFormation Generation]
A --> A3[Type Safety]
end
subgraph "โ๏ธ AWS Services"
B[CloudFormation] --> B1[Resource Provisioning]
B --> B2[Dependency Management]
B --> B3[Rollback Capabilities]
C[VPC] --> C1[Network Isolation]
C --> C2[Security Groups]
C --> C3[Subnets]
end
subgraph "๐ Security"
D[IAM] --> D1[Role-based Access]
D --> D2[Permission Policies]
D --> D3[Cross-account Access]
E[Secrets Manager] --> E1[Secure Configuration]
E --> E2[Encryption]
E --> E3[Rotation]
end
subgraph "๐ Monitoring"
F[CloudWatch] --> F1[Logs]
F --> F2[Metrics]
F --> F3[Alarms]
G[X-Ray] --> G1[Distributed Tracing]
G --> G2[Performance Analysis]
end
end
classDef iac fill:#ff6b35,stroke:#f7931e,stroke-width:2px
classDef aws fill:#ff9900,stroke:#232f3e,stroke-width:2px
classDef security fill:#ff6b6b,stroke:#ee5a52,stroke-width:2px
classDef monitoring fill:#4ecdc4,stroke:#44a08d,stroke-width:2px
class A,A1,A2,A3 iac
class B,B1,B2,B3,C,C1,C2,C3 aws
class D,D1,D2,D3,E,E1,E2,E3 security
class F,F1,F2,F3,G,G1,G2 monitoring
๐ Development Workflow
Local Development Flow
graph LR
subgraph "๐ป Local Development"
A[๐ Code Changes] --> B[๐ Hot Reload]
B --> C[๐งช Run Tests]
C --> D[๐ Type Checking]
D --> E[๐จ Lint & Format]
E --> F[โ
Ready to Deploy]
G[๐ Start Dev Server] --> H[๐ Local Testing]
H --> I[๐ Debug Issues]
I --> A
end
classDef dev fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
classDef test fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
classDef quality fill:#fff3e0,stroke:#f57c00,stroke-width:2px
class A,B,G,H,I dev
class C,D test
class E,F quality
Deployment Pipeline
graph TB
subgraph "๐ Deployment Pipeline"
A[๐ฆ Code Commit] --> B[๐งช Automated Tests]
B --> C[๐ Code Review]
C --> D[๐๏ธ Build & Package]
D --> E[๐ Deploy to Environment]
subgraph "๐ Environments"
F[๐ Local] --> G[๐ง Development]
G --> H[โ
Validation]
H --> I[๐ Production]
end
E --> F
F --> G
G --> H
H --> I
J[๐ Monitoring] --> K[๐ Alerts]
K --> L[๐ Rollback if needed]
end
classDef pipeline fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
classDef env fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
classDef monitor fill:#fff3e0,stroke:#f57c00,stroke-width:2px
class A,B,C,D,E pipeline
class F,G,H,I env
class J,K,L monitor
๐ Code Quality & Testing
Testing Strategy
graph TB
subgraph "๐งช Testing Strategy"
subgraph "๐ฌ Unit Testing"
A[Vitest] --> A1[Lambda Functions]
A --> A2[Utility Functions]
A --> A3[React Components]
end
subgraph "๐ Integration Testing"
B[API Testing] --> B1[End-to-end API calls]
B --> B2[Database operations]
B --> B3[External service integration]
end
subgraph "๐ญ E2E Testing"
C[Playwright] --> C1[User journey testing]
C --> C2[Cross-browser testing]
C --> C3[Performance testing]
end
subgraph "๐ Quality Checks"
D[TypeScript] --> D1[Type checking]
D --> D2[Compilation validation]
E[ESLint] --> E1[Code linting]
E --> E2[Style enforcement]
F[Prettier] --> F1[Code formatting]
end
end
classDef unit fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
classDef integration fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
classDef e2e fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
classDef quality fill:#fff3e0,stroke:#f57c00,stroke-width:2px
class A,A1,A2,A3 unit
class B,B1,B2,B3 integration
class C,C1,C2,C3 e2e
class D,D1,D2,E,E1,E2,F,F1 quality
๐ Performance & Scalability
Performance Architecture
graph TB
subgraph "โก Performance Architecture"
subgraph "๐ Frontend Performance"
A[Vite] --> A1[Fast Development]
A --> A2[Optimized Builds]
B[Code Splitting] --> B1[Route-based splitting]
B --> B2[Lazy loading]
C[CloudFront] --> C1[Global CDN]
C --> C2[Edge caching]
end
subgraph "โ๏ธ Backend Performance"
D[Serverless] --> D1[Auto-scaling]
D --> D2[Pay-per-use]
E[Connection Pooling] --> E1[Database optimization]
F[Caching] --> F1[API Gateway cache]
F --> F2[CloudFront cache]
end
subgraph "๐ Async Processing"
G[SQS] --> G1[Background tasks]
G --> G2[Message queuing]
H[Event-driven] --> H1[Lambda triggers]
H --> H2[Real-time processing]
end
end
classDef frontend fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
classDef backend fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
classDef async fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
class A,A1,A2,B,B1,B2,C,C1,C2 frontend
class D,D1,D2,E,E1,F,F1,F2 backend
class G,G1,G2,H,H1,H2 async
๐ Security Architecture
Security Layers
graph TB
subgraph "๐ก๏ธ Security Architecture"
subgraph "๐ Authentication"
A[Cognito User Pools] --> A1[User management]
A --> A2[Multi-factor auth]
B[Identity Pools] --> B1[AWS resource access]
C[JWT Tokens] --> C1[Stateless auth]
end
subgraph "๐ Authorization"
D[IAM Roles] --> D1[Fine-grained permissions]
D --> D2[Least privilege access]
E[API Gateway] --> E1[Request validation]
E --> E2[Rate limiting]
end
subgraph "๐ Data Security"
F[Encryption at Rest] --> F1[S3 encryption]
F --> F2[OpenSearch encryption]
G[Encryption in Transit] --> G1[TLS/SSL everywhere]
H[Secrets Manager] --> H1[Secure configuration]
H --> H2[Automatic rotation]
end
subgraph "๐ Network Security"
I[VPC] --> I1[Network isolation]
I --> I2[Private subnets]
J[Security Groups] --> J1[Firewall rules]
K[NACLs] --> K1[Network ACLs]
end
end
classDef auth fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
classDef authz fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
classDef data fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
classDef network fill:#fff3e0,stroke:#f57c00,stroke-width:2px
class A,A1,A2,B,B1,C,C1 auth
class D,D1,D2,E,E1,E2 authz
class F,F1,F2,G,G1,H,H1,H2 data
class I,I1,I2,J,J1,K,K1 network
๐ Monitoring & Observability
Observability Stack
graph TB
subgraph "๐ Observability Stack"
subgraph "๐ Logging"
A[CloudWatch Logs] --> A1[Centralized logging]
A --> A2[Structured JSON logs]
A --> A3[Log levels]
end
subgraph "๐ Monitoring"
B[CloudWatch Metrics] --> B1[Performance metrics]
B --> B2[Custom metrics]
C[CloudWatch Alarms] --> C1[Automated alerting]
C --> C2[Threshold monitoring]
end
subgraph "๐ Tracing"
D[X-Ray] --> D1[Distributed tracing]
D --> D2[Performance analysis]
D --> D3[Service map]
end
subgraph "๐ฅ Health Checks"
E[Health Endpoints] --> E1[Application health]
E --> E2[Dependency health]
F[Uptime Monitoring] --> F1[Availability tracking]
end
end
classDef logging fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
classDef monitoring fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
classDef tracing fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
classDef health fill:#fff3e0,stroke:#f57c00,stroke-width:2px
class A,A1,A2,A3 logging
class B,B1,B2,C,C1,C2 monitoring
class D,D1,D2,D3 tracing
class E,E1,E2,F,F1 health
This analysis provides a comprehensive understanding of the MacPro Mako codebase structure and the technologies used,
visualized with colorful Mermaid diagrams. The application follows modern cloud-native patterns with a focus on
scalability, maintainability, and developer experience.
๐ฏ Key Takeaways
- ๐๏ธ Monorepo Architecture: Single repository with clear separation of concerns
- โ๏ธ Serverless First: Built entirely on AWS serverless services
- ๐ Security Focused: Multiple layers of security for healthcare data
- ๐ฑ Modern Frontend: React 18 with TypeScript and modern tooling
- โก High Performance: CDN, caching, and auto-scaling
- ๐งช Comprehensive Testing: Unit, integration, and E2E testing
- ๐ Full Observability: Logging, monitoring, and tracing
- ๐ CI/CD Ready: Automated deployment pipeline