# finnishtransportagency/hassu architecture

> Architecture diagram of the GitHub repository finnishtransportagency/hassu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/finnishtransportagency/hassu
- Repository: https://github.com/finnishtransportagency/hassu

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: CDN & Edge
    subgraph "Layer 1: CDN & Edge"
        direction TB
        CloudFront["CloudFront Distribution"]:::cdn
        FEEdgeReq["Lambda@Edge: Request Rewriting"]:::lambda
        FEEdgeAuth["Lambda@Edge: Signed-Cookie Auth"]:::lambda
        FEEdgeOrigin["Lambda@Edge: Origin Response Auth"]:::lambda
    end

    %% Layer 2: Frontend
    subgraph "Layer 2: Frontend (Next.js)"
        direction TB
        Pages["src/pages"]:::frontend
        Components["src/components"]:::frontend
        APIClient["services/api.ts"]:::frontend
    end

    %% Layer 3: API Layer
    subgraph "Layer 3: API Layer"
        direction TB
        APIGateway["API Gateway"]:::api
        APIHandler["backend/src/apiHandler.ts"]:::lambda
        APIPublic["backend/src/apiHandlerJulkinen.ts"]:::lambda
    end

    %% Layer 4: Compute (Lambdas)
    subgraph "Layer 4: Compute (Lambdas)"
        direction TB
        FileHandler["fileHandler Lambda"]:::lambda
        EmailHandler["emailHandler Lambda"]:::lambda
        DocHandler["asiakirjaHandler Lambda"]:::lambda
        SQSEventHandler["sqsEventHandler Lambda"]:::lambda
        Scheduler["endDateCalculatorHandler Lambda"]:::lambda
    end

    %% Layer 5: Services & Adapters
    subgraph "Layer 5: Services & Adapters"
        direction TB
        AWSAdapters["backend/src/aws"]:::service
        DBRepositories["backend/src/database"]:::service
        S3Cache["backend/src/cache/s3Cache.ts"]:::service
        EmailSvc["backend/src/email"]:::service
        DocSvc["backend/src/asiakirja"]:::service
        FileSvc["backend/src/files/fileService.ts"]:::service
        PreConsult["backend/src/ennakkoneuvottelu"]:::service
    end

    %% Layer 6: Persistence & Search
    subgraph "Layer 6: Persistence & Search"
        direction TB
        DynamoDB["DynamoDB Tables"]:::database
        OpenSearch["OpenSearch Domain"]:::database
        S3Bucket["S3 Buckets"]:::database
    end

    %% Layer 7: Messaging & Events
    subgraph "Layer 7: Messaging & Events"
        direction TB
        SQSQueue["SQS Queues"]:::database
    end

    %% Layer 8: External Integrations
    subgraph "Layer 8: External Integrations"
        direction TB
        Velho["Velho Service"]:::external
        SuomiFi["Suomi.fi Service"]:::external
        MML["MML/PRH Service"]:::external
        AsianHallinta["Asianhallinta Service"]:::external
    end

    %% Layer 9: Deployment & Infra
    subgraph "Layer 9: Deployment & Infra"
        direction TB
        ServerlessYML["serverless.yml"]:::infra
        CDK["cdk.json / cdk-config.json"]:::infra
        DeploymentScripts["deployment/"]:::infra
    end

    %% Connections
    Browser["User Browser"]:::frontend -->|requests| CloudFront
    CloudFront -->|serves static/SSR| Pages
    Pages -->|uses| Components
    Components -->|calls API| APIClient
    APIClient -->|HTTP/GraphQL| APIGateway
    APIGateway -->|routes| APIHandler
    APIGateway -->|routes public| APIPublic
    APIHandler -->|invokes| FileHandler
    APIHandler -->|invokes| EmailHandler
    APIHandler -->|invokes| DocHandler
    APIHandler -->|publishes SQS| SQSEventHandler
    APIHandler -->|scheduled trigger| Scheduler
    FileHandler -->|uses| FileSvc
    FileHandler -->|stores| S3Bucket
    FileHandler -->|enqueues| SQSQueue
    SQSEventHandler -->|updates| DBRepositories
    SQSEventHandler -->|indexes| OpenSearch
    DocHandler -->|uses| DocSvc
    DocHandler -->|stores| S3Bucket
    EmailHandler -->|uses| EmailSvc
    EmailHandler -->|publishes| SQSQueue
    Scheduler -->|reads/writes| DBRepositories
    APIHandler -->|uses| AWSAdapters
    APIHandler -->|uses| DBRepositories
    APIHandler -->|uses| S3Cache
    APIHandler -->|integrates| Velho
    APIHandler -->|integrates| SuomiFi
    APIHandler -->|integrates| MML
    APIHandler -->|integrates| AsianHallinta

    ServerlessYML -->|defines| APIGateway
    ServerlessYML -->|defines| FileHandler
    ServerlessYML -->|defines| EmailHandler
    ServerlessYML -->|defines| DocHandler
    ServerlessYML -->|defines| SQSEventHandler
    ServerlessYML -->|defines| Scheduler
    CDK -->|provisions| CloudFront
    CDK -->|provisions| S3Bucket
    CDK -->|provisions| Cognito

    %% Click Events
    click Pages "https://github.com/finnishtransportagency/hassu/tree/main/src/pages"
    click Components "https://github.com/finnishtransportagency/hassu/tree/main/src/components"
    click APIClient "https://github.com/finnishtransportagency/hassu/blob/main/src/services/api.ts"
    click FEEdgeReq "https://github.com/finnishtransportagency/hassu/blob/main/deployment/lib/lambda/frontendRequest.js"
    click FEEdgeAuth "https://github.com/finnishtransportagency/hassu/blob/main/deployment/lib/lambda/suomifiHeader.js"
    click FEEdgeOrigin "https://github.com/finnishtransportagency/hassu/blob/main/deployment/lib/lambda/tiedostotOriginResponse.js"
    click APIHandler "https://github.com/finnishtransportagency/hassu/blob/main/backend/src/apiHandler.ts"
    click APIPublic "https://github.com/finnishtransportagency/hassu/blob/main/backend/src/apiHandlerJulkinen.ts"
    click FileHandler "https://github.com/finnishtransportagency/hassu/blob/main/backend/src/handler/fileHandler.ts"
    click EmailHandler "https://github.com/finnishtransportagency/hassu/blob/main/backend/src/handler/email/emailHandler.ts"
    click DocHandler "https://github.com/finnishtransportagency/hassu/blob/main/backend/src/handler/asiakirjaHandler.ts"
    click SQSEventHandler "https://github.com/finnishtransportagency/hassu/blob/main/backend/src/sqsEvents/sqsEventHandlerLambda.ts"
    click Scheduler "https://github.com/finnishtransportagency/hassu/blob/main/backend/src/endDateCalculator/endDateCalculatorHandler.ts"
    click AWSAdapters "https://github.com/finnishtransportagency/hassu/tree/main/backend/src/aws"
    click DBRepositories "https://github.com/finnishtransportagency/hassu/tree/main/backend/src/database"
    click S3Cache "https://github.com/finnishtransportagency/hassu/blob/main/backend/src/cache/s3Cache.ts"
    click EmailSvc "https://github.com/finnishtransportagency/hassu/tree/main/backend/src/email"
    click DocSvc "https://github.com/finnishtransportagency/hassu/tree/main/backend/src/asiakirja"
    click FileSvc "https://github.com/finnishtransportagency/hassu/blob/main/backend/src/files/fileService.ts"
    click PreConsult "https://github.com/finnishtransportagency/hassu/tree/main/backend/src/ennakkoneuvottelu"
    click DynamoDB "https://github.com/finnishtransportagency/hassu/tree/main/backend/src/database"
    click OpenSearch "https://github.com/finnishtransportagency/hassu/tree/main/backend/src/projektiSearch"
    click SQSQueue "https://github.com/finnishtransportagency/hassu/tree/main/backend/src/sqsEvents"
    click Velho "https://github.com/finnishtransportagency/hassu/tree/main/backend/src/velho"
    click SuomiFi "https://github.com/finnishtransportagency/hassu/tree/main/backend/src/suomifi"
    click MML "https://github.com/finnishtransportagency/hassu/tree/main/backend/src/mml"
    click AsianHallinta "https://github.com/finnishtransportagency/hassu/tree/main/backend/src/asianhallinta"
    click ServerlessYML "https://github.com/finnishtransportagency/hassu/blob/main/serverless.yml"
    click CDK "https://github.com/finnishtransportagency/hassu/blob/main/cdk.json"
    click DeploymentScripts "https://github.com/finnishtransportagency/hassu/tree/main/deployment/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef cdn fill:#E0F7FA,stroke:#0097A7,color:#006064;
    classDef api fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef lambda fill:#FFD54F,stroke:#FFB300,color:#BF360C;
    classDef service fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20;
    classDef database fill:#C8E6C9,stroke:#388E3C,color:#1B5E20;
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#37474F;
    classDef infra fill:#F5F5F5,stroke:#9E9E9E,color:#424242;
```
