# thaikhangvip123/cloud-service architecture

> Architecture diagram of the GitHub repository thaikhangvip123/cloud-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thaikhangvip123/cloud-service
- Repository: https://github.com/thaikhangvip123/cloud-service

## Overview

This is a serverless, group-based Just-in-Time AWS access portal. Jira requests enter through API Gateway and the executor validates and provisions temporary Identity Center group membership, records an active session, updates Jira, and schedules expiry. Expiry removes membership and archives the session; a documented SIT-only DynamoDB TTL stream is a fallback. A separate email-approval path issues single-use signed links and updates Jira. Terraform establishes the permanent permission sets, groups, and assignments. The workflow and optional email path are documented; unsampled Terraform wiring is represented only where the README states it.

Main entry points: [`infrastructure/lambda_functions/executor/handler.py`](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/lambda_functions/executor/handler.py) (Request executor), [`infrastructure/lambda_functions/email_approval/handler.py`](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/lambda_functions/email_approval/handler.py) (Email approval handler), [`infrastructure/lambda_functions/expiry/handler.py`](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/lambda_functions/expiry/handler.py) (Expiry handler), [`infrastructure/shared/email_notification.py`](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/email_notification.py) (Email notifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request handling"]
  node_executor["Request executor<br/>[handler.py]"]
  node_auth["Webhook validation<br/>[webhook_auth.py]"]
end

subgraph group_domain["JIT access domain"]
  node_jit["JIT access manager<br/>[jit_access.py]"]
  node_mapping["Access group mapping<br/>[account_mapping.py]"]
  node_identity["Identity Center client<br/>[identity_center.py]"]
  node_jira["Jira client<br/>[jira_client.py]"]
  node_notifier["Email notifier"]
end

subgraph group_state["Session state and expiry"]
  node_repository["Session repository"]
  node_sessions[("Active sessions")]
  node_scheduler["Expiry scheduler<br/>[scheduler.py]"]
  node_expiry["Expiry handler<br/>[handler.py]"]
end

subgraph group_approval["Email approval"]
  node_approval_handler["Email approval handler<br/>[handler.py]"]
  node_tokens["Approval tokens<br/>[approval_tokens.py]"]
  node_token_store[("Token records")]
end

subgraph group_foundation["AWS foundation"]
  node_terraform["Terraform access foundation"]
  node_permission_sets["Permission sets and assignments<br/>[main.tf]"]
end

node_jira_actor(("Jira requester"))
node_api["API Gateway"]
node_eventbridge["EventBridge Scheduler"]
node_ttl_stream["DynamoDB TTL stream"]
node_ses["Amazon SES"]
node_approver(("Email approver"))
node_secrets[("Secrets Manager")]

node_jira_actor -->|"submits request"| node_api
node_api -->|"routes webhook"| node_executor
node_executor -->|"validates request"| node_auth
node_executor -->|"provisions access"| node_jit
node_executor -->|"stores session"| node_repository
node_executor -->|"updates request"| node_jira
node_executor -->|"sends grant notice"| node_notifier
node_jit -->|"resolves group"| node_mapping
node_jit -->|"changes membership"| node_identity
node_repository -->|"reads and writes"| node_sessions
node_executor -->|"schedules expiry"| node_scheduler
node_scheduler -->|"creates schedule"| node_eventbridge
node_eventbridge -->|"invokes at expiry"| node_expiry
node_ttl_stream -.->|"fallback trigger"| node_expiry
node_expiry -->|"loads and archives"| node_repository
node_expiry -->|"removes membership"| node_identity
node_expiry -->|"marks expired"| node_jira
node_expiry -->|"sends expiry notice"| node_notifier
node_notifier -->|"delivers email"| node_ses
node_jira_actor -.->|"requests approval"| node_approval_handler
node_approval_handler -->|"generates tokens"| node_tokens
node_approval_handler -->|"stores token records"| node_repository
node_tokens -->|"verifies single use"| node_token_store
node_approval_handler -->|"sends approval link"| node_notifier
node_ses -->|"delivers link"| node_approver
node_approver -.->|"opens action link"| node_approval_handler
node_approval_handler -->|"records decision"| node_jira
node_executor -.->|"loads credentials"| node_secrets
node_approval_handler -.->|"loads approval secrets"| node_secrets
node_terraform -.->|"defines access model"| node_permission_sets

click node_executor "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/lambda_functions/executor/handler.py"
click node_auth "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/webhook_auth.py"
click node_jit "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/jit_access.py"
click node_mapping "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/account_mapping.py"
click node_identity "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/identity_center.py"
click node_jira "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/jira_client.py"
click node_repository "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/dynamodb_session.py"
click node_scheduler "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/scheduler.py"
click node_expiry "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/lambda_functions/expiry/handler.py"
click node_notifier "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/email_notification.py"
click node_approval_handler "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/lambda_functions/email_approval/handler.py"
click node_tokens "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/approval_tokens.py"
click node_terraform "https://github.com/thaikhangvip123/cloud-service/tree/main/infrastructure/terraform"
click node_permission_sets "https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/terraform/modules/identity-center-permission-sets/main.tf"

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_executor,node_auth toneBlue
class node_jit,node_mapping,node_identity,node_jira,node_notifier,node_secrets toneAmber
class node_repository,node_sessions,node_scheduler,node_expiry,node_jira_actor,node_api toneMint
class node_approval_handler,node_tokens,node_token_store,node_eventbridge toneRose
class node_terraform,node_permission_sets,node_ttl_stream,node_ses,node_approver toneIndigo
```

## Components

### Request handling

- [Request executor](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/lambda_functions/executor/handler.py): `infrastructure/lambda_functions/executor/handler.py`
- [Webhook validation](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/webhook_auth.py): `infrastructure/shared/webhook_auth.py`

### JIT access domain

- [JIT access manager](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/jit_access.py): `infrastructure/shared/jit_access.py`
- [Access group mapping](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/account_mapping.py): `infrastructure/shared/account_mapping.py`
- [Identity Center client](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/identity_center.py): `infrastructure/shared/identity_center.py`
- [Jira client](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/jira_client.py): `infrastructure/shared/jira_client.py`
- [Email notifier](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/email_notification.py): `infrastructure/shared/email_notification.py`

### Session state and expiry

- [Session repository](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/dynamodb_session.py): `infrastructure/shared/dynamodb_session.py`
- **Active sessions**
- [Expiry scheduler](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/scheduler.py): `infrastructure/shared/scheduler.py`
- [Expiry handler](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/lambda_functions/expiry/handler.py): `infrastructure/lambda_functions/expiry/handler.py`

### Email approval

- [Email approval handler](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/lambda_functions/email_approval/handler.py): `infrastructure/lambda_functions/email_approval/handler.py`
- [Approval tokens](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/shared/approval_tokens.py): `infrastructure/shared/approval_tokens.py`
- **Token records**

### AWS foundation

- [Terraform access foundation](https://github.com/thaikhangvip123/cloud-service/tree/main/infrastructure/terraform): `infrastructure/terraform`
- [Permission sets and assignments](https://github.com/thaikhangvip123/cloud-service/blob/main/infrastructure/terraform/modules/identity-center-permission-sets/main.tf): `infrastructure/terraform/modules/identity-center-permission-sets/main.tf`

### Other components

- **Jira requester**
- **API Gateway**
- **EventBridge Scheduler**
- **DynamoDB TTL stream**
- **Amazon SES**
- **Email approver**
- **Secrets Manager**

## Connections

- Jira requester → API Gateway: submits request (evidence: `README.md`)
- API Gateway → Request executor: routes webhook (evidence: `README.md`)
- Request executor → Webhook validation: validates request (evidence: `infrastructure/lambda_functions/executor/handler.py`)
- Request executor → JIT access manager: provisions access (evidence: `infrastructure/lambda_functions/executor/handler.py`)
- Request executor → Session repository: stores session (evidence: `infrastructure/lambda_functions/executor/handler.py`)
- Request executor → Jira client: updates request (evidence: `README.md`)
- Request executor → Email notifier: sends grant notice (evidence: `infrastructure/lambda_functions/executor/handler.py`)
- JIT access manager → Access group mapping: resolves group (evidence: `infrastructure/shared/jit_access.py`)
- JIT access manager → Identity Center client: changes membership (evidence: `README.md`)
- Session repository → Active sessions: reads and writes (evidence: `README.md`)
- Request executor → Expiry scheduler: schedules expiry (evidence: `infrastructure/lambda_functions/executor/handler.py`)
- Expiry scheduler → EventBridge Scheduler: creates schedule (evidence: `README.md`)
- EventBridge Scheduler → Expiry handler: invokes at expiry (evidence: `README.md`)
- DynamoDB TTL stream → Expiry handler: fallback trigger (evidence: `README.md`)
- Expiry handler → Session repository: loads and archives (evidence: `infrastructure/lambda_functions/expiry/handler.py`)
- Expiry handler → Identity Center client: removes membership (evidence: `infrastructure/lambda_functions/expiry/handler.py`)
- Expiry handler → Jira client: marks expired (evidence: `infrastructure/lambda_functions/expiry/handler.py`)
- Expiry handler → Email notifier: sends expiry notice (evidence: `infrastructure/lambda_functions/expiry/handler.py`)
- Email notifier → Amazon SES: delivers email (evidence: `infrastructure/shared/email_notification.py`)
- Jira requester → Email approval handler: requests approval (evidence: `README.md`)
- Email approval handler → Approval tokens: generates tokens (evidence: `infrastructure/lambda_functions/email_approval/handler.py`)
- Email approval handler → Session repository: stores token records (evidence: `infrastructure/lambda_functions/email_approval/handler.py`)
- Approval tokens → Token records: verifies single use
- Email approval handler → Email notifier: sends approval link (evidence: `infrastructure/lambda_functions/email_approval/handler.py`)
- Amazon SES → Email approver: delivers link
- Email approver → Email approval handler: opens action link (evidence: `README.md`)
- Email approval handler → Jira client: records decision (evidence: `infrastructure/lambda_functions/email_approval/handler.py`)
- Request executor → Secrets Manager: loads credentials (evidence: `README.md`)
- Email approval handler → Secrets Manager: loads approval secrets (evidence: `README.md`)
- Terraform access foundation → Permission sets and assignments: defines access model (evidence: `README.md`)