# uatisdeproblem/esn-assembly architecture

> Architecture diagram of the GitHub repository uatisdeproblem/esn-assembly, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uatisdeproblem/esn-assembly
- Repository: https://github.com/uatisdeproblem/esn-assembly

## Overview

#### Purpose and Entry Points
ESN Assembly is a full-stack platform for National Organization assemblies: content and Q&A topics, opportunities and applications, communications, deadlines, badges, and public/secret voting. The Ionic/Angular client starts at `front-end/src/main.ts` and composes routing and shared state through `front-end/src/app/app.module.ts` and `front-end/src/app/app.routing.module.ts`. The TypeScript AWS CDK application starts at `back-end/deploy/main.ts`.

#### Front-End Application Shell
The client is an Ionic Angular SPA organized around tabbed feature modules. Application initialization, authentication enforcement, and cross-feature API/session behavior are centralized in `front-end/src/app/init.guard.ts`, `front-end/src/app/auth.guard.ts`, and `front-end/src/app/app.service.ts`. Routes lead into dashboard, topics, opportunities, profile, and voting areas under `front-end/src/app/tabs/`.

#### Backend API and Domain Handlers
Backend functionality is implemented as handler-per-resource/serverless endpoints, with the API contract in `back-end/swagger.yaml`. Core domain handlers include topics/Q&A (`back-end/src/handlers/topics.ts`, `back-end/src/handlers/questions.ts`, `back-end/src/handlers/answers.ts`), opportunities/applications (`back-end/src/handlers/opportunities.ts`, `back-end/src/handlers/applications.ts`), and voting (`back-end/src/handlers/votingSessions.ts`, `back-end/src/handlers/vote.ts`). Domain shapes are explicit TypeScript models in `back-end/src/models/`.

#### Assembly Content and Interaction Flow
Administrators configure events, categories, and platform settings; users consume dashboard material and engage with topics. The client’s dashboard and configuration boundaries are `front-end/src/app/tabs/dashboard/dashboard.module.ts` and `front-end/src/app/tabs/configurations/configurations.module.ts`; corresponding backend resources are `back-end/src/handlers/events.ts`, `back-end/src/handlers/categories.ts`, and `back-end/src/handlers/configurations.ts`. Topics support messages, questions, answers, reactions, drafts, and related-topic relationships via handlers such as `back-end/src/handlers/messages.ts`, `back-end/src/handlers/questionsUpvotes.ts`, and `back-end/src/handlers/userDrafts.ts`.

#### Opportunities and Voting Workflows
Opportunities expose open calls and application review: UI entry points are `front-end/src/app/tabs/opportunities/opportunities.page.ts` and `front-end/src/app/tabs/opportunities/applications/reviewApplication.component.ts`, backed by opportunity and application handlers. Voting separates session setup, voter/ballot management, vote casting, and archived results under `front-end/src/app/tabs/voting/`; persistent concepts are modeled by `back-end/src/models/votingSession.model.ts`, `back-end/src/models/votingTicket.model.ts`, and `back-end/src/models/votingResult.model.ts`.

#### Infrastructure and External Boundaries
AWS CDK provisions the service topology in separated stacks: API (`back-end/deploy/api-stack.ts`), custom API domain (`back-end/deploy/api-domain-stack.ts`), media (`back-end/deploy/media-stack.ts`), email (`back-end/deploy/ses-stack.ts`), and frontend hosting (`back-end/deploy/front-end-stack.ts`). Deployment environments are selected through `back-end/deploy/environments.ts`. Email notification templates in `back-end/assets/` are delivered through SES-facing logic in `back-end/src/handlers/sesNotifications.ts`; media is accessed through `back-end/src/handlers/media.ts` and `front-end/src/app/common/media.service.ts`.

#### Real-Time and Notification Paths
The backend includes WebSocket handling (`back-end/src/handlers/webSocket.ts`, `back-end/src/models/webSocket.model.ts`) for real-time interaction boundaries. Business events can produce notification emails, including new questions/answers, application decisions, and voting instructions, using templates such as `back-end/assets/notify-new-question.hbs` and `back-end/assets/notify-voting-instructions.hbs`.

Main entry points: [`front-end/src/app/app.module.ts`](https://github.com/uatisdeproblem/esn-assembly/blob/main/front-end/src/app/app.module.ts) (App shell and routes), [`back-end/deploy/main.ts`](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/deploy/main.ts) (CDK application), [`back-end/deploy/api-stack.ts`](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/deploy/api-stack.ts) (API stack), [`back-end/src/handlers/topics.ts`](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/topics.ts) (Content and Q&A handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Ionic Angular Client"]
  node_client_entry["SPA entry point<br/>Angular bootstrap<br/>[main.ts]"]
  node_app_shell["App shell and routes<br/>Angular modules<br/>[app.module.ts]"]
  node_dashboard_config["Dashboard and configuration<br/>feature modules"]
  node_topics_ui["Topics and Q&amp;A<br/>tab feature"]
  node_opportunities_ui["Opportunities review<br/>tab workflow"]
  node_voting_ui["Voting workflow<br/>tab feature"]
  node_media_client["Media client<br/>Angular service<br/>[media.service.ts]"]
end

subgraph group_backend["Serverless Backend"]
  node_api_contract["API contract<br/>OpenAPI<br/>[swagger.yaml]"]
  node_content_handlers["Content and Q&amp;A handlers<br/>Lambda handlers<br/>[topics.ts]"]
  node_opportunity_handlers["Opportunity handlers<br/>Lambda handlers<br/>[opportunities.ts]"]
  node_voting_handlers["Voting handlers<br/>Lambda handlers<br/>[votingSessions.ts]"]
  node_assembly_handlers["Assembly configuration handlers<br/>Lambda handlers<br/>[events.ts]"]
  node_domain_models["Domain models<br/>TypeScript models"]
  node_realtime_handlers["WebSocket handlers<br/>real-time endpoint<br/>[webSocket.ts]"]
  node_notification_handlers["Email notifications<br/>SES handler"]
  node_media_handlers["Media handlers<br/>media endpoint<br/>[media.ts]"]
end

subgraph group_infra["AWS CDK Deployment"]
  node_cdk_app{{"CDK application<br/>deployment entry point<br/>[main.ts]"}}
  node_api_stack["API stack<br/>CDK stack<br/>[api-stack.ts]"]
  node_media_stack["Media stack<br/>CDK stack<br/>[media-stack.ts]"]
  node_email_stack["Email stack<br/>CDK stack<br/>[ses-stack.ts]"]
  node_hosting_stack["Frontend hosting stack<br/>CDK stack<br/>[front-end-stack.ts]"]
end

subgraph group_external["AWS Boundaries"]
  node_ses{{"Amazon SES<br/>email delivery"}}
end

node_client_entry -->|"bootstraps"| node_app_shell
node_app_shell -->|"routes to"| node_dashboard_config
node_app_shell -->|"routes to"| node_topics_ui
node_app_shell -->|"routes to"| node_opportunities_ui
node_app_shell -->|"routes to"| node_voting_ui
node_app_shell -->|"uses API"| node_api_contract
node_topics_ui -->|"content and Q&amp;A"| node_content_handlers
node_opportunities_ui -->|"applications"| node_opportunity_handlers
node_voting_ui -->|"votes"| node_voting_handlers
node_dashboard_config -->|"assembly settings"| node_assembly_handlers
node_media_client -->|"media access"| node_media_handlers
node_content_handlers -->|"uses"| node_domain_models
node_opportunity_handlers -->|"uses"| node_domain_models
node_voting_handlers -->|"uses voting models"| node_domain_models
node_content_handlers -.->|"question and answer events"| node_notification_handlers
node_opportunity_handlers -.->|"decision events"| node_notification_handlers
node_voting_handlers -.->|"voting instructions"| node_notification_handlers
node_notification_handlers -->|"delivers email"| node_ses
node_cdk_app -->|"provisions"| node_api_stack
node_cdk_app -->|"provisions"| node_media_stack
node_cdk_app -->|"provisions"| node_email_stack
node_cdk_app -->|"provisions"| node_hosting_stack
node_api_stack -->|"deploys endpoints"| node_content_handlers
node_api_stack -->|"deploys endpoints"| node_opportunity_handlers
node_api_stack -->|"deploys endpoints"| node_voting_handlers
node_media_stack -->|"hosts media boundary"| node_media_handlers
node_email_stack -->|"configures"| node_ses
node_hosting_stack -->|"hosts SPA"| node_client_entry

click node_client_entry "https://github.com/uatisdeproblem/esn-assembly/blob/main/front-end/src/main.ts"
click node_app_shell "https://github.com/uatisdeproblem/esn-assembly/blob/main/front-end/src/app/app.module.ts"
click node_dashboard_config "https://github.com/uatisdeproblem/esn-assembly/blob/main/front-end/src/app/tabs/dashboard/dashboard.module.ts"
click node_opportunities_ui "https://github.com/uatisdeproblem/esn-assembly/blob/main/front-end/src/app/tabs/opportunities/opportunities.page.ts"
click node_media_client "https://github.com/uatisdeproblem/esn-assembly/blob/main/front-end/src/app/common/media.service.ts"
click node_api_contract "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/swagger.yaml"
click node_content_handlers "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/topics.ts"
click node_opportunity_handlers "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/opportunities.ts"
click node_voting_handlers "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/votingSessions.ts"
click node_assembly_handlers "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/events.ts"
click node_realtime_handlers "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/webSocket.ts"
click node_notification_handlers "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/sesNotifications.ts"
click node_media_handlers "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/media.ts"
click node_cdk_app "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/deploy/main.ts"
click node_api_stack "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/deploy/api-stack.ts"
click node_media_stack "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/deploy/media-stack.ts"
click node_email_stack "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/deploy/ses-stack.ts"
click node_hosting_stack "https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/deploy/front-end-stack.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_client_entry,node_app_shell,node_dashboard_config,node_topics_ui,node_opportunities_ui,node_voting_ui,node_media_client toneBlue
class node_api_contract,node_content_handlers,node_opportunity_handlers,node_voting_handlers,node_assembly_handlers,node_domain_models,node_realtime_handlers,node_notification_handlers,node_media_handlers toneAmber
class node_cdk_app,node_api_stack,node_media_stack,node_email_stack,node_hosting_stack toneMint
class node_ses toneRose
```

## Components

### Ionic Angular Client

- [SPA entry point](https://github.com/uatisdeproblem/esn-assembly/blob/main/front-end/src/main.ts): Angular bootstrap · `front-end/src/main.ts`
- [App shell and routes](https://github.com/uatisdeproblem/esn-assembly/blob/main/front-end/src/app/app.module.ts): Angular modules · Composes routing, guards, shared API, and session behavior. · `front-end/src/app/app.module.ts`
- [Dashboard and configuration](https://github.com/uatisdeproblem/esn-assembly/blob/main/front-end/src/app/tabs/dashboard/dashboard.module.ts): feature modules · `front-end/src/app/tabs/dashboard/dashboard.module.ts`
- **Topics and Q&A**: tab feature
- [Opportunities review](https://github.com/uatisdeproblem/esn-assembly/blob/main/front-end/src/app/tabs/opportunities/opportunities.page.ts): tab workflow · `front-end/src/app/tabs/opportunities/opportunities.page.ts`
- **Voting workflow**: tab feature · Session setup, ballots, casting, and archived results.
- [Media client](https://github.com/uatisdeproblem/esn-assembly/blob/main/front-end/src/app/common/media.service.ts): Angular service · `front-end/src/app/common/media.service.ts`

### Serverless Backend

- [API contract](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/swagger.yaml): OpenAPI · `back-end/swagger.yaml`
- [Content and Q&A handlers](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/topics.ts): Lambda handlers · Topics, messages, questions, answers, reactions, and drafts. · `back-end/src/handlers/topics.ts`
- [Opportunity handlers](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/opportunities.ts): Lambda handlers · Open calls, applications, and review decisions. · `back-end/src/handlers/opportunities.ts`
- [Voting handlers](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/votingSessions.ts): Lambda handlers · Sessions, voter ballots, vote casting, and results. · `back-end/src/handlers/votingSessions.ts`
- [Assembly configuration handlers](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/events.ts): Lambda handlers · Events, categories, and platform settings. · `back-end/src/handlers/events.ts`
- **Domain models**: TypeScript models · Shared resource and voting persistence shapes.
- [WebSocket handlers](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/webSocket.ts): real-time endpoint · `back-end/src/handlers/webSocket.ts`
- [Email notifications](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/sesNotifications.ts): SES handler · Sends business-event notifications from templates. · `back-end/src/handlers/sesNotifications.ts`
- [Media handlers](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/src/handlers/media.ts): media endpoint · `back-end/src/handlers/media.ts`

### AWS CDK Deployment

- [CDK application](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/deploy/main.ts): deployment entry point · Selects environments and provisions separated service stacks. · `back-end/deploy/main.ts`
- [API stack](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/deploy/api-stack.ts): CDK stack · `back-end/deploy/api-stack.ts`
- [Media stack](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/deploy/media-stack.ts): CDK stack · `back-end/deploy/media-stack.ts`
- [Email stack](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/deploy/ses-stack.ts): CDK stack · `back-end/deploy/ses-stack.ts`
- [Frontend hosting stack](https://github.com/uatisdeproblem/esn-assembly/blob/main/back-end/deploy/front-end-stack.ts): CDK stack · `back-end/deploy/front-end-stack.ts`

### AWS Boundaries

- **Amazon SES**: email delivery

## Connections

- SPA entry point → App shell and routes: bootstraps
- App shell and routes → Dashboard and configuration: routes to
- App shell and routes → Topics and Q&A: routes to
- App shell and routes → Opportunities review: routes to
- App shell and routes → Voting workflow: routes to
- App shell and routes → API contract: uses API
- Topics and Q&A → Content and Q&A handlers: content and Q&A
- Opportunities review → Opportunity handlers: applications
- Voting workflow → Voting handlers: votes
- Dashboard and configuration → Assembly configuration handlers: assembly settings
- Media client → Media handlers: media access
- Content and Q&A handlers → Domain models: uses
- Opportunity handlers → Domain models: uses
- Voting handlers → Domain models: uses voting models
- Content and Q&A handlers → Email notifications: question and answer events
- Opportunity handlers → Email notifications: decision events
- Voting handlers → Email notifications: voting instructions
- Email notifications → Amazon SES: delivers email
- CDK application → API stack: provisions
- CDK application → Media stack: provisions
- CDK application → Email stack: provisions
- CDK application → Frontend hosting stack: provisions
- API stack → Content and Q&A handlers: deploys endpoints
- API stack → Opportunity handlers: deploys endpoints
- API stack → Voting handlers: deploys endpoints
- Media stack → Media handlers: hosts media boundary
- Email stack → Amazon SES: configures
- Frontend hosting stack → SPA entry point: hosts SPA