# tonikiri666/hassu architecture

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

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

## Overview

##### Project type and purpose
- Full-stack web application “Hassu”
- Front-end: Next.js React UI, server-rendered pages, static assets and API routes
- Back-end: AWS Lambda-based API (Serverless Framework or CDK), handling project management workflows, document generation, file storage, messaging and search
- Shared domain code in “common” and reusable Lambda layers

##### File structure analysis
- Top-level directories
- backend/ – all Lambda handlers, business logic, integration with DynamoDB, S3, SQS, OpenSearch, external systems (Velho, suomifi, MML, PRH), PDF generation
- src/ (root) – Next.js app: pages/, components/, hooks/, services/, API routes under pages/api
- common/ – shared TypeScript types, GraphQL schema stubs, validation, utilities used by both front- and back-end
- layers/ – AWS Lambda layers (e.g. lambda-base)
- deployment/ – CDK/Serverless infra definitions, pipeline scripts, IAM setup, localstack config
- graphql/ – GraphQL schema and codegen configuration
- cypress/ – end-to-end tests
- Patterns
- Backend: handler/adaptor pattern per feature (e.g. HyvaksymisEsitys, aloitekuulutus)
- AWS service clients organized under aws/, sqsEvents/, personSearch/, projektiSearch/
- Separation of concerns: “handler” (Lambda entry point) → “service” (business logic) → “database” (persistence) → “adapter” (external API transform)
- Front-end: page/component/hook/service layers, Next.js API routes for SSR and client API proxy

##### README insights
- Deploys via npm scripts: deploy:backend, deploy:frontend, deploy:app
- Relies on AWS Systems Manager Parameter Store for secrets and configuration
- CI/CD pipeline bootstrapped via deploy:pipeline
- GraphQL code generation step

a. Main components
- Front-end (Next.js app)
- API Gateway (or Next.js API routes)
- AWS Lambda functions (grouped by domain modules)
- AWS SQS queues (event bus for file processing, zip tasks)
- AWS S3 buckets (file storage, PDF assets)
- AWS DynamoDB (projekti data, short URL lookup)
- AWS OpenSearch (projektihaku, muistuttaja and omistaja search)
- AWS Lambda layers (shared utils)
- CDK/Serverless Framework (infrastructure as code)
- External services: Velho APIs, suomifi WS, MML, PRH
- CI/CD Pipeline (CodePipeline/BuildSpec via deployment/)

b. Relationships and interactions
1. User’s browser → CloudFront → Next.js front-end
2. Front-end → API Gateway or Next.js API routes → Lambda functions
3. Lambda interacts with DynamoDB for CRUD, S3 for file I/O, SQS to enqueue background tasks
4. File events on SQS → Lambda “sqsEventHandlerLambda” → file persistence, zip generation, notifications
5. DynamoDB streams → Lambda “projektiSearch” → OpenSearch indexing
6. Lambdas call external WS/APIs (Velho, suomifi, MML) via aws/clients or generated SDK under backend/src/velho
7. PDF generation: Lambda “asiakirjaHandler” → file stored to S3 → URL returned to front-end
8. CDK/Serverless deploys all resources, IAM roles, pipelines, CloudFront distributions

c. Architectural patterns and principles
- Serverless microservices: each domain feature as separate Lambda
- Event-driven: SQS, DynamoDB Streams
- Adapter/Mapper layers for external systems and for API⇄DB transformations
- Infrastructure as Code: CDK or serverless.yml scripts
- Shared business logic in Lambda layers and common/ package

d. Key technologies and frameworks
- Next.js, React, TypeScript
- AWS Lambda, API Gateway, SQS, S3, DynamoDB, OpenSearch
- CDK/Serverless Framework for infra
- Cypress for E2E
- GraphQL codegen (common/graphql)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        CF["CloudFront"]:::infra
        FrontendApp["Next.js App"]:::compute
        ApiRoutes["Next.js API Routes"]:::compute
    end

    %% Backend Layer
    subgraph "Backend Layer"
        API["API Gateway / Next.js API"]:::compute
        subgraph "Lambda Functions" 
            LambdaHandlers["Lambda Handlers"]:::compute
            PdfGenerator["PDF Generator Lambda"]:::compute
            AsiadkService["Asiakirja Service"]:::compute
            HyvaksysAction["HyvaksymisEsitys Actions"]:::compute
            SqsHandler["SQS Event Handler"]:::compute
            ProjektiSearch["Projekti Search Lambdas"]:::compute
            FileService["File Service"]:::compute
        end
    end

    %% Data Stores
    subgraph "Data Stores"
        DynamoDB["DynamoDB"]:::data
        S3["S3 Bucket"]:::data
        SQS["SQS Queues"]:::integration
        OpenSearch["OpenSearch"]:::data
    end

    %% External Integrations
    subgraph "External Services"
        VelhoClient["Velho API"]:::integration
        SuomifiHandler["suomifi WS"]:::integration
        MmlClient["MML Client"]:::integration
        KiinteistoHandler["MML Kiinteisto Handler"]:::integration
        Prh["PRH Service"]:::integration
    end

    %% Infra & Shared
    subgraph "Infrastructure & Shared"
        Layers["Lambda Layers"]:::infra
        Common["common/"]:::infra
        Deployment["CDK/Serverless Deployment"]:::infra
        Graphql["GraphQL Codegen"]:::infra
        CiCd["CI/CD Pipeline"]:::infra
        Cypress["Cypress Tests"]:::infra
    end

    %% Sync flows
    Browser["User Browser"]:::external -->|HTTP| CF
    CF -->|HTTP| FrontendApp
    FrontendApp -->|API Call| ApiRoutes
    ApiRoutes -->|Invoke| LambdaHandlers
    LambdaHandlers -->|calls| AsiadkService
    AsiadkService -->|CRUD| DynamoDB
    AsiadkService -->|read/write| S3
    AsiadkService -->|enqueue| SQS

    LambdaHandlers -->|generate PDF| PdfGenerator
    PdfGenerator -->|store PDF| S3
    PdfGenerator -->|return URL| ApiRoutes

    LambdaHandlers -->|adapt| HyvaksysAction
    HyvaksysAction -->|invoke| ProjektiSearch

    %% Async flows
    SQS -.->|message| SqsHandler
    SqsHandler -->|process| FileService
    FileService -->|store| S3

    DynamoDB -.->|stream| ProjektiSearch
    ProjektiSearch -->|index| OpenSearch

    %% External calls
    LambdaHandlers -->|call| VelhoClient
    LambdaHandlers -->|call| SuomifiHandler
    LambdaHandlers -->|call| MmlClient
    LambdaHandlers -->|call| KiinteistoHandler
    LambdaHandlers -->|call| Prh

    %% Infra & Shared usage
    LambdaHandlers -->|use| Layers
    AsiadkService -->|use| Common
    ApiRoutes -->|use| Common
    Deployment -->|provisions| CF
    Deployment -->|provisions| API
    Deployment -->|provisions| LambdaHandlers
    Deployment -->|provisions| DynamoDB
    Deployment -->|provisions| S3
    Deployment -->|provisions| SQS
    Deployment -->|provisions| OpenSearch
    Deployment -->|runs| CiCd
    Graphql -->|outputs types| Common
    CiCd -->|runs tests| Cypress

    %% Click Events
    click FrontendApp "https://github.com/tonikiri666/hassu/tree/main/src/"
    click ApiRoutes "https://github.com/tonikiri666/hassu/tree/main/src/pages/api"
    click LambdaHandlers "https://github.com/tonikiri666/hassu/tree/main/backend/src/handler"
    click PdfGenerator "https://github.com/tonikiri666/hassu/blob/main/backend/src/asiakirja/lambda/pdfGeneratorHandler.ts"
    click AsiadkService "https://github.com/tonikiri666/hassu/blob/main/backend/src/asiakirja/asiakirjaService.ts"
    click HyvaksysAction "https://github.com/tonikiri666/hassu/tree/main/backend/src/HyvaksymisEsitys/actions"
    click SqsHandler "https://github.com/tonikiri666/hassu/blob/main/backend/src/sqsEvents/sqsEventHandlerLambda.ts"
    click ProjektiSearch "https://github.com/tonikiri666/hassu/tree/main/backend/src/projektiSearch"
    click FileService "https://github.com/tonikiri666/hassu/blob/main/backend/src/files/fileService.ts"
    click VelhoClient "https://github.com/tonikiri666/hassu/blob/main/backend/src/velho/velhoClient.ts"
    click SuomifiHandler "https://github.com/tonikiri666/hassu/blob/main/backend/src/suomifi/suomifiHandler.ts"
    click MmlClient "https://github.com/tonikiri666/hassu/blob/main/backend/src/mml/mmlClient.ts"
    click KiinteistoHandler "https://github.com/tonikiri666/hassu/blob/main/backend/src/mml/kiinteistoHandler.ts"
    click Prh "https://github.com/tonikiri666/hassu/blob/main/backend/src/mml/prh/prh.ts"
    click Common "https://github.com/tonikiri666/hassu/tree/main/common/"
    click Layers "https://github.com/tonikiri666/hassu/tree/main/layers/lambda-base"
    click Deployment "https://github.com/tonikiri666/hassu/tree/main/deployment/"
    click Graphql "https://github.com/tonikiri666/hassu/tree/main/graphql/"
    click CiCd "https://github.com/tonikiri666/hassu/tree/main/deployment/lib/buildspec"
    click Cypress "https://github.com/tonikiri666/hassu/tree/main/cypress/"

    %% Styles
    classDef compute fill:#BBDEFB,stroke:#333,stroke-width:1px
    classDef data fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef integration fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef infra fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef external fill:#F5F5F5,stroke:#999,stroke-width:1px,stroke-dasharray: 2 2
```
