System Architecture
This section provides technical deep-dives for advanced developers and architects who need to understand how the FanFest platform components communicate, how events flow through the system, and how authentication works end to end.
High-Level Architecture
The FanFest platform is composed of four major subsystems that communicate through well-defined boundaries:
Component Summary
| Component | Technology | Responsibility |
|---|---|---|
| FanFest SDK | TypeScript, Vite | Event tracking, embed management, silent authentication |
| FanFest Web App | Vue.js, Vite | Full fan engagement UI rendered inside an iframe |
| API Function | Node.js, Express, TypeGraphQL, TypeDI | GraphQL API, REST endpoints, business logic |
| Auth Function | Node.js, Express | OIDC provider, token issuance, silent auth flows |
| EventBridge | AWS EventBridge | Async event routing between services |
| Worker Functions | Node.js Lambda | Translations, email, content moderation, chain publishing |
| PostgreSQL | AWS RDS, Prisma ORM | Primary data store for all domain entities |
| DynamoDB | AWS DynamoDB | Auth transaction state (short-lived, TTL-managed) |
EventBridge Event Flow
The API publishes domain events to an EventBridge event bus. EventBridge rules route these events to SQS queues, which trigger worker Lambda functions for async processing.
Event Types
The MessageBroker service publishes four event types:
| Event Type | Source | Purpose | Target Queue |
|---|---|---|---|
ContentUpserted | vip.fanfest.api | Content created or updated (shows, threads, quizzes, etc.) | Translations, Email |
ContentTranslated | vip.fanfest.translations | Translation completed for content | Email (notifications) |
ContentReported | vip.fanfest.api | User reports content (chat messages, threads) | Content Moderation |
UserActionCreated | vip.fanfest.api | User completed a loyalty action | Chain Publisher |
Content Types
The event system handles these content types for translation and notification workflows:
Show, Topic, ContestPrize, Raffle, Quiz, QuizQuestion, QuizQuestionOption, Thread, ChatMessage, LeaderboardPrize, ChatRoom, AppAction, ChannelAction, ChannelMembership, ChannelRole.
Authentication Architecture
FanFest implements a custom OIDC provider that supports two authentication channels: external SSO providers (OAuth) and one-time password (OTP) via SMS/email.
OIDC Silent Authentication Flow
The silent auth flow enables seamless SSO where users authenticated on the host site are automatically authenticated in the FanFest embed without any visible login step.
Key Security Properties
- PKCE (Proof Key for Code Exchange): All authorization flows use SHA-256 code challenges to prevent code interception.
- Origin Validation: The auth function validates that the requesting origin matches the registered web app origins. Redirect URIs are checked against an allowlist.
- Token Rotation: Refresh tokens use rotation with parent tracking. Each refresh produces a new token and invalidates the old one.
- Transaction TTL: Auth transactions in DynamoDB have time-to-live, automatically expiring stale flows.
- Hidden Iframe Isolation: The silent auth iframe is invisible (1x1px, opacity 0, fixed positioning) and is destroyed after authentication completes.
Authentication Channels
| Channel | When Used | Flow |
|---|---|---|
| External Provider (OAuth) | User has an SSO provider configured (Auth0, Keycloak, etc.) | Standard OIDC authorize/callback/token flow via the host's identity provider |
| OTP (One-Time Password) | User authenticates via phone number or email | login_hint parameter triggers OTP flow; code delivered via Twilio |
OIDC Discovery
The auth function exposes standard OIDC discovery endpoints:
/.well-known/openid-configuration-- Discovery document/.well-known/jwks.json-- JSON Web Key Set for token verification/auth/authorize-- Authorization endpoint/auth/callback-- Callback endpoint (receives provider redirects)/auth/token-- Token endpoint (authorization_code and refresh_token grants)/oauth/userinfo-- User info endpoint
API Architecture
The main API function serves both GraphQL and REST endpoints, deployed as a single Lambda function behind API Gateway.
Request Flow
- API Gateway receives HTTP requests and proxies to the Lambda function via
serverless-http - Express routes requests -- GraphQL queries go to the TypeGraphQL schema, REST endpoints go to Express routers
- Resolvers are thin wrappers that handle authorization and argument parsing, then delegate to services
- Services contain business logic and are injected via TypeDI's
@Service()/@Inject()decorators - Repositories encapsulate data access through Prisma ORM
- MessageBroker publishes async events to EventBridge for background processing
Lambda Functions Overview
| Function | Trigger | Purpose |
|---|---|---|
api | API Gateway (HTTP) | Main GraphQL + REST API |
auth | API Gateway (HTTP) | OIDC provider, authentication flows |
translations-queue | SQS | Auto-translate content via AI |
email-queue | SQS | Send notification emails |
content-moderation-queue | SQS | AI-based content moderation |
chain-publisher-queue | SQS | Publish loyalty actions to blockchain |
mediaconvert-queue | SNS | Process video encoding callbacks |
mediaconvert-upload-queue | SQS | Handle media upload processing |
eventbridge-dlq-processor | SQS (DLQ) | Log and alert on failed event deliveries |
api-health | Schedule (1 min) | Health monitoring |
auth-txn-rotation | Schedule (1 hour) | Clean up expired auth transactions |
auth-vault-rotate | Schedule (daily) | Rotate signing keys |
account-deletion-cron | Schedule (12 hours) | Process account deletion requests |
data-retention-cron | Schedule (7 days) | Enforce data retention policies |
SDK-to-Frontend Communication
The SDK and the FanFest frontend (running inside an iframe) communicate exclusively through the browser's postMessage API. See SDK Internals for the complete PostMessage protocol specification.
The iframe is sandboxed with a restricted permission set: allow-same-origin, allow-scripts, allow-forms, allow-modals, allow-popups. It also declares feature permissions for autoplay, camera, fullscreen, microphone, and clipboard-read/clipboard-write.
Next Steps
- SDK Internals -- PostMessage protocol, state management, and build architecture
- Integration Guide -- Integration tiers and implementation options
- SSO Setup -- Step-by-step SSO configuration