How uatisdeproblem/esn-assembly works
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: app.module.ts App shell and routes · main.ts CDK application · api-stack.ts API stack · topics.ts Content and Q&A handlers
Components 22
Ionic Angular Client
- SPA entry point
front-end/src/main.ts - App shell and routes · Composes routing, guards, shared API, and session behavior.
front-end/src/app/app.module.ts - Dashboard and configuration
front-end/src/app/tabs/dashboard/dashboard.module.ts - Topics and Q&A
- Opportunities review
front-end/src/app/tabs/opportunities/opportunities.page.ts - Voting workflow · Session setup, ballots, casting, and archived results.
- Media client
front-end/src/app/common/media.service.ts
Serverless Backend
- API contract
back-end/swagger.yaml - Content and Q&A handlers · Topics, messages, questions, answers, reactions, and drafts.
back-end/src/handlers/topics.ts - Opportunity handlers · Open calls, applications, and review decisions.
back-end/src/handlers/opportunities.ts - Voting handlers · Sessions, voter ballots, vote casting, and results.
back-end/src/handlers/votingSessions.ts - Assembly configuration handlers · Events, categories, and platform settings.
back-end/src/handlers/events.ts - Domain models · Shared resource and voting persistence shapes.
- WebSocket handlers
back-end/src/handlers/webSocket.ts - Email notifications · Sends business-event notifications from templates.
back-end/src/handlers/sesNotifications.ts - Media handlers
back-end/src/handlers/media.ts
AWS CDK Deployment
- CDK application · Selects environments and provisions separated service stacks.
back-end/deploy/main.ts - API stack
back-end/deploy/api-stack.ts - Media stack
back-end/deploy/media-stack.ts - Email stack
back-end/deploy/ses-stack.ts - Frontend hosting stack
back-end/deploy/front-end-stack.ts
AWS Boundaries
- Amazon SES
Connections 28
- 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