# alexhddev/cdk-course-resources architecture

> Architecture diagram of the GitHub repository alexhddev/cdk-course-resources, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexhddev/cdk-course-resources
- Repository: https://github.com/alexhddev/cdk-course-resources

## Overview

#### Purpose and Repository Layout
This is a collection of AWS CDK course projects. The primary application is `space-finder`: a serverless “spaces” API with authentication, data storage, monitoring, and a separately deployed React frontend. `cdk-starter` and `cdk-cicd` are smaller CDK examples/templates; `s3template.json` is a standalone CloudFormation template.

#### Primary Application Entry Points
CDK deployment composition starts at `space-finder/src/infra/Launcher.ts`, which instantiates infrastructure stacks. Lambda service entry points are organized under `space-finder/src/services`, notably `spaces/handler.ts` for the spaces API and `monitor/handler.ts` for monitoring. The browser application starts at `space-finder-frontend/src/main.tsx` and renders `space-finder-frontend/src/App.tsx`.

#### Infrastructure Stack Boundaries
`space-finder/src/infra/stacks/AuthStack.ts` provisions the authentication boundary, while `DataStack.ts` owns persistence resources. `LambdaStack.ts` packages and exposes backend Lambda functions; `ApiStack.ts` connects HTTP API routes to those functions. This separates resource ownership from API wiring and allows stacks to exchange generated resource references.

#### Spaces API and Domain Flow
Requests enter the API infrastructure, invoke the spaces Lambda handler, then dispatch to operation-specific services:
- Read: `space-finder/src/services/spaces/GetSpaces.ts`
- Create: `space-finder/src/services/spaces/PostSpaces.ts` and document-aware `PostSpacesWithDoc.ts`
- Update/delete: `space-finder/src/services/spaces/UpdateSpace.ts`, `DeleteSpace.ts`
- Routing/error boundary: `space-finder/src/services/spaces/handler.ts`

Domain types reside in `space-finder/src/services/model/Model.ts`. Shared validation and response/utilities are centralized in `space-finder/src/services/shared/Validator.ts` and `space-finder/src/services/shared/Utils.ts`.

#### Frontend and Backend Integration
The Vite/React frontend presents login, navigation, listing, and space creation workflows through `space-finder-frontend/src/components/LoginComponent.tsx`, `components/spaces/Spaces.tsx`, and `components/spaces/CreateSpace.tsx`. It crosses the browser/service boundary through `space-finder-frontend/src/services/AuthService.ts` and `src/services/DataService.ts`, which should consume deployed auth and API endpoints rather than direct infrastructure resources.

#### Deployment, Hosting, and Operations
`space-finder/src/infra/stacks/UiDeploymentStack.ts` deploys the frontend, implying static-site hosting backed by AWS infrastructure. `MonitorStack.ts` and `services/monitor/handler.ts` form a distinct monitoring path, likely collecting or reporting operational signals independently of CRUD handlers. Material runtime/services are TypeScript on Node.js, AWS CDK/CloudFormation, Lambda, an API layer, authentication service, data store, and static UI hosting.

#### Supporting CDK Examples
`cdk-starter/bin/cdk-starter.ts` launches a basic stack set including `PhotosStack.ts` and `PhotosHandlerStack.ts`. `cdk-cicd/bin/cdk-cicd.ts` launches a CI/CD-oriented CDK app composed from `lib/cdk-cicd-stack.ts`, `PipelineStage.ts`, and `LambdaStack.ts`; its sample Lambda is `cdk-cicd/services/hello.ts`.

Main entry points: [`space-finder/src/infra/Launcher.ts`](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/Launcher.ts) (CDK launcher), [`space-finder/src/services/spaces/GetSpaces.ts`](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/services/spaces/GetSpaces.ts) (Space operations), [`space-finder/src/infra/stacks/LambdaStack.ts`](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/LambdaStack.ts) (Lambda stack), [`space-finder-frontend/src/services/AuthService.ts`](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder-frontend/src/services/AuthService.ts) (Auth and data clients)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_primary["Space Finder"]
  node_auth(("Authentication<br/>AWS auth service"))
  node_data_store[("Spaces data store<br/>AWS data store")]
  node_http_api{{"Spaces HTTP API<br/>AWS API layer"}}
  node_spaces_handler["Spaces handler<br/>Lambda handler<br/>[handler.ts]"]
  node_space_operations["Space operations<br/>service layer<br/>[GetSpaces.ts]"]
  node_domain_shared["Domain and shared utilities<br/>domain layer<br/>[Model.ts]"]
  node_monitor_handler["Monitor handler<br/>Lambda handler<br/>[handler.ts]"]
end

subgraph group_infra["CDK Infrastructure"]
  node_launcher{{"CDK launcher<br/>CDK app<br/>[Launcher.ts]"}}
  node_auth_stack["Auth stack<br/>CDK stack<br/>[AuthStack.ts]"]
  node_data_stack["Data stack<br/>CDK stack<br/>[DataStack.ts]"]
  node_lambda_stack["Lambda stack<br/>CDK stack<br/>[LambdaStack.ts]"]
  node_api_stack["API stack<br/>CDK stack<br/>[ApiStack.ts]"]
  node_ui_stack["UI deployment stack<br/>CDK stack"]
  node_monitor_stack["Monitor stack<br/>CDK stack<br/>[MonitorStack.ts]"]
end

subgraph group_frontend["React Frontend"]
  node_frontend_main["Frontend bootstrap<br/>Vite React entry<br/>[main.tsx]"]
  node_frontend_app["Spaces UI<br/>React application<br/>[App.tsx]"]
  node_frontend_services["Auth and data clients<br/>browser services<br/>[AuthService.ts]"]
end

subgraph group_examples["CDK Examples"]
  node_starter_app{{"Starter CDK app<br/>CDK example<br/>[cdk-starter.ts]"}}
  node_cicd_app{{"CI/CD CDK app<br/>CDK example<br/>[cdk-cicd.ts]"}}
end

node_launcher -->|"instantiates"| node_auth_stack
node_launcher -->|"instantiates"| node_data_stack
node_launcher -->|"instantiates"| node_lambda_stack
node_launcher -->|"instantiates"| node_api_stack
node_launcher -->|"instantiates"| node_ui_stack
node_launcher -->|"instantiates"| node_monitor_stack
node_auth_stack -->|"provisions"| node_auth
node_data_stack -->|"provisions"| node_data_store
node_lambda_stack -->|"packages"| node_spaces_handler
node_lambda_stack -->|"packages"| node_monitor_handler
node_api_stack -->|"exposes"| node_http_api
node_http_api -->|"invokes"| node_spaces_handler
node_spaces_handler -->|"dispatches"| node_space_operations
node_space_operations -->|"uses"| node_domain_shared
node_space_operations -->|"reads and writes"| node_data_store
node_ui_stack -->|"deploys"| node_frontend_main
node_frontend_main -->|"renders"| node_frontend_app
node_frontend_app -->|"uses"| node_frontend_services
node_frontend_services -->|"authenticates with"| node_auth
node_frontend_services -->|"calls"| node_http_api
node_monitor_stack -->|"deploys"| node_monitor_handler
node_starter_app -.-> node_cicd_app

click node_launcher "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/Launcher.ts"
click node_auth_stack "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/AuthStack.ts"
click node_data_stack "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/DataStack.ts"
click node_lambda_stack "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/LambdaStack.ts"
click node_api_stack "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/ApiStack.ts"
click node_ui_stack "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/UiDeploymentStack.ts"
click node_monitor_stack "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/MonitorStack.ts"
click node_spaces_handler "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/services/spaces/handler.ts"
click node_space_operations "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/services/spaces/GetSpaces.ts"
click node_domain_shared "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/services/model/Model.ts"
click node_monitor_handler "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/services/monitor/handler.ts"
click node_frontend_main "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder-frontend/src/main.tsx"
click node_frontend_app "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder-frontend/src/App.tsx"
click node_frontend_services "https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder-frontend/src/services/AuthService.ts"
click node_starter_app "https://github.com/alexhddev/cdk-course-resources/blob/main/cdk-starter/bin/cdk-starter.ts"
click node_cicd_app "https://github.com/alexhddev/cdk-course-resources/blob/main/cdk-cicd/bin/cdk-cicd.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth,node_data_store,node_http_api,node_spaces_handler,node_space_operations,node_domain_shared,node_monitor_handler toneBlue
class node_launcher,node_auth_stack,node_data_stack,node_lambda_stack,node_api_stack,node_ui_stack,node_monitor_stack toneAmber
class node_frontend_main,node_frontend_app,node_frontend_services toneMint
class node_starter_app,node_cicd_app toneRose
```

## Components

### Space Finder

Primary serverless application.

- **Authentication**: AWS auth service
- **Spaces data store**: AWS data store
- **Spaces HTTP API**: AWS API layer
- [Spaces handler](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/services/spaces/handler.ts): Lambda handler · Routes requests and handles errors. · `space-finder/src/services/spaces/handler.ts`
- [Space operations](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/services/spaces/GetSpaces.ts): service layer · Read, create, document create, update, and delete operations. · `space-finder/src/services/spaces/GetSpaces.ts`
- [Domain and shared utilities](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/services/model/Model.ts): domain layer · Models, validation, and response utilities. · `space-finder/src/services/model/Model.ts`
- [Monitor handler](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/services/monitor/handler.ts): Lambda handler · Independent operational reporting path. · `space-finder/src/services/monitor/handler.ts`

### CDK Infrastructure

- [CDK launcher](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/Launcher.ts): CDK app · Composes the primary deployment stacks. · `space-finder/src/infra/Launcher.ts`
- [Auth stack](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/AuthStack.ts): CDK stack · Owns authentication resources. · `space-finder/src/infra/stacks/AuthStack.ts`
- [Data stack](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/DataStack.ts): CDK stack · Owns persistence resources. · `space-finder/src/infra/stacks/DataStack.ts`
- [Lambda stack](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/LambdaStack.ts): CDK stack · Packages backend functions. · `space-finder/src/infra/stacks/LambdaStack.ts`
- [API stack](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/ApiStack.ts): CDK stack · Wires HTTP routes to functions. · `space-finder/src/infra/stacks/ApiStack.ts`
- [UI deployment stack](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/UiDeploymentStack.ts): CDK stack · Deploys static frontend hosting. · `space-finder/src/infra/stacks/UiDeploymentStack.ts`
- [Monitor stack](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder/src/infra/stacks/MonitorStack.ts): CDK stack · Deploys the monitoring path. · `space-finder/src/infra/stacks/MonitorStack.ts`

### React Frontend

- [Frontend bootstrap](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder-frontend/src/main.tsx): Vite React entry · `space-finder-frontend/src/main.tsx`
- [Spaces UI](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder-frontend/src/App.tsx): React application · Login, listing, and creation workflows. · `space-finder-frontend/src/App.tsx`
- [Auth and data clients](https://github.com/alexhddev/cdk-course-resources/blob/main/space-finder-frontend/src/services/AuthService.ts): browser services · Consumes deployed auth and API endpoints. · `space-finder-frontend/src/services/AuthService.ts`

### CDK Examples

- [Starter CDK app](https://github.com/alexhddev/cdk-course-resources/blob/main/cdk-starter/bin/cdk-starter.ts): CDK example · Launches photo-related stacks. · `cdk-starter/bin/cdk-starter.ts`
- [CI/CD CDK app](https://github.com/alexhddev/cdk-course-resources/blob/main/cdk-cicd/bin/cdk-cicd.ts): CDK example · Composes pipeline, stack, and sample Lambda. · `cdk-cicd/bin/cdk-cicd.ts`

## Connections

- CDK launcher → Auth stack: instantiates
- CDK launcher → Data stack: instantiates
- CDK launcher → Lambda stack: instantiates
- CDK launcher → API stack: instantiates
- CDK launcher → UI deployment stack: instantiates
- CDK launcher → Monitor stack: instantiates
- Auth stack → Authentication: provisions
- Data stack → Spaces data store: provisions
- Lambda stack → Spaces handler: packages
- Lambda stack → Monitor handler: packages
- API stack → Spaces HTTP API: exposes
- Spaces HTTP API → Spaces handler: invokes
- Spaces handler → Space operations: dispatches
- Space operations → Domain and shared utilities: uses
- Space operations → Spaces data store: reads and writes
- UI deployment stack → Frontend bootstrap: deploys
- Frontend bootstrap → Spaces UI: renders
- Spaces UI → Auth and data clients: uses
- Auth and data clients → Authentication: authenticates with
- Auth and data clients → Spaces HTTP API: calls
- Monitor stack → Monitor handler: deploys
- Starter CDK app → CI/CD CDK app