How finnishtransportagency/hassu works
Project type and purpose
• This is a full-stack, single-page application built with Next.js (React/TypeScript) for the frontend and a Node.js/TypeScript serverless backend running on AWS Lambda.
• It manages “projekti” (projects) workflows: filing, document generation (PDFs), email notifications, state transitions, and integrates with external services (Velho, Suomi.fi, PRH, bank-holiday API, etc.).
High-level architectural components
a. Frontend (Next.js)
– Next.js pages (src/pages) + React components (src/components)
– Static assets served from S3/CloudFront
– GraphQL or REST client (services/api.ts) calling backend API
b. CDN & Edge
– AWS CloudFront distribution in front of both frontend and API
– Lambda@Edge for request rewriting and signed-cookie authentication
c. API Gateway & Lambda
– API Gateway (HTTP/REST or GraphQL endpoints) routes to Lambda functions
– Lambdas grouped by domain: apiHandler, asiakirjaHandler (PDF), emailHandler, fileHandler, sqsEventHandler, personSearchUpdaterHandler, etc.
d. Business-logic and service layer
– handler/ → HTTP-triggered Lambdas invoking services under aws/, database/, s3Calls/, email/, asiakirja/, etc.
– Common adapter layers (adaptToAPI, adaptToSave, adaptToDB) implement a hexagonal pattern.
e. Persistence and cache
– DynamoDB tables (projekti, palaute, muistuttaja, omistaja, lyhytOsoite, …)
– OpenSearch for full-text search (projektiSearch, omistajaSearch, muistuttajaSearch)
– S3 for file storage and S3Cache
f. Messaging & events
– SQS queues (eventSqsClient.ts) for file processing, zip tasks, email events, scheduled tasks
– Lambda triggers on SQS events
g. External services
– Velho (municipal project registry) via generated OpenAPI client
– Suomi.fi authentication (SOAP/WSDL client under suomifi/)
– PRH, MML, bank-holiday service, Asianhallinta (document management)
h. Deployment & infra
– CDK (cdk.json) and Serverless (serverless.yml) to define Lambdas, API Gateway, DynamoDB tables, S3 buckets, CloudFront, Parameter Store, Cognito, WAF, pipelines
– CI/CD scripts under deployment/ to provision dev/test/prod stacks
Relationships and data flow
1. User in browser → CloudFront → Next.js frontend → calls backend API (via API Gateway)
2. API Gateway → Lambda (apiHandler) → invokes domain-specific handlers → services → DynamoDB/OpenSearch/S3 → returns response
3. File upload → API Gateway → Lambda (fileHandler) → S3.putFile → publishes SQS event → Lambda (sqsEventHandler) processes file metadata → updates DB
4. Document generation → user triggers via frontend → Lambda (asiakirjaHandler) → invokes PDF generator Lambda → stores file in S3 → returns download link
5. Email notifications → code enqueues messages to SQS → emailHandler Lambda → SES (or external mail service) → updates DB
6. Scheduled tasks → Lambda (scheduler) triggered by EventBridge → e.g., end-of-phase transitions, reminder emails
7. Search sync → DynamoDB streams → Lambda (projektiSearchIndexer) → OpenSearch
8. External integrations → synchronous calls from Lambdas to Velho/Suomi.fi/MML/PRH services
Architectural patterns and design principles
• Layered, hexagonal architecture: handlers → adapters → services → repositories
• Event-driven: SQS and DynamoDB streams to decouple file processing, search indexing, email sending
• Infrastructure as code: CDK + Serverless for reproducible environments
• CI/CD pipelines: separate deployment of backend, frontend, pipelines
• Domain-driven organization: folders by feature (asiakirja, projekti, palaute, muistutus, …)
Detail level
– Capture all major AWS services deployed by CDK/Serverless (API GW, Lambda, DynamoDB tables, S3 buckets, SQS queues, OpenSearch domains, Cognito, CloudFront)
– Show the event-driven connections (SQS → Lambda, DynamoDB streams → OpenSearch)
– Highlight external integration flows (Velho API, Suomi.fi WS)
– Optionally annotate with security boundaries (Cognito authorizer, BasicAuth proxy, IAM roles, VPC if used)