# finnishtransportagency/digiroad2 architecture

> Architecture diagram of the GitHub repository finnishtransportagency/digiroad2, 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/digiroad2
- Repository: https://github.com/finnishtransportagency/digiroad2

## Overview

##### Project type & purpose
- Digiroad2 is a full-stack, GIS-focused asset management application.
- It comprises:
- A rich client UI (vanilla JS/LESS/HTML built via Grunt)
- A Scala/SBT‐powered REST API server (Scalatra)
- Geo-processing logic (digiroad2-geo)
- Oracle/PostGIS persistence modules (digiroad2-oracle, digiroad2-api-common)
- CI/CD and infra provisioning (AWS CloudFormation, ECS Fargate, CodeArtifact, CodeBuild, RDS/Postgres or Oracle, ElastiCache, SNS, S3, Batch/Lambda)

##### File structure & architectural hints
- UI/ – front-end code, static assets, tests, Grunt build → client runs in browser
- src/main/scala/ – Scalatra bootstrap & server → single JVM process exposing REST endpoints
- digiroad2-api-* & digiroad2-geo & digiroad2-oracle modules → core libraries packaged/injected at runtime
- aws/cloud-formation & aws/fargate – infra definitions for container deployment, networking, DB, cache, message topics, batch jobs
- local-dev – Docker Compose setup for local PostGIS emulation
- build tooling: Grunt for UI; SBT for server; npm/CodeArtifact for JS packages; CloudFormation/CLI scripts for deployment

##### Key README insights
- Local setup involves dockerized PostGIS, Grunt watch/server, and running the Scala server via SBT.
- Production uses AWS: ECR/ECS‐Fargate tasks behind an ALB, RDS or Oracle, ElastiCache, SNS, S3 buckets, Parameter Store for secrets.
- CI pipelines defined in CloudFormation (CodeBuild/CodePipeline).

##### Components
A. Client tier
– Browser: static UI assets (HTML/JS/CSS) served either from S3 (prod) or local Grunt server (dev)
– Integration tests / RobotFramework tests for end-to-end verification
B. API tier
– ECS Fargate task running the Scala Scalatra container
– REST endpoints (Digiroad2Api) serving geo/assets CRUD, import/export, CSV user management
C. Data tier
– RDS Postgres (dev) / Oracle DB (prod via digiroad2-oracle module)
– ElastiCache (Redis) for caching road link data
– S3 buckets for static hosting (UI, swagger UI) and data import/export
D. Infrastructure & services
– ALB (Application Load Balancer) → routes /api/* to ECS tasks, /static to S3
– IAM Roles/Parameter Store for secrets & config
– CloudWatch Logs & Metrics
– CodeArtifact (npm repo) & ECR (Docker images)
– CodeBuild/CodePipeline (CI/CD)
– SNS Topics for user notifications
– BatchSystem & Lambda for scheduled batch processes (e.g., data import/export)
E. External integrations
– VVH & VKM REST APIs (via client modules)
– Google Maps & raster services (apiKey stashed in env)

##### Relationships & data flows
- Browser → ALB → ECS REST API
- API → RDS/Postgres or Oracle (JDBC via BoneCP)
- API ↔ Redis cache (road link & session caching)
- API → S3 (read/write static assets, CSV import/export)
- API ↔ External REST services (VVH, VKM)
- CI/CD: GitHub → CodeBuild → ECR → ECS (via CloudFormation/CodePipeline)
- Scheduled batch jobs: AWS Batch → Lambdas → Database

##### Architectural patterns & principles
- Layered monolith: front-end, API, domain logic (geo, import/export), persistence.
- Clear separation of concerns: modules for authentication, authorization policies, geo computations, DB DAO/services.
- Infrastructure-as-code: all AWS resources described in CloudFormation.
- Containerization: UI and API packaged as Docker images (Fargate).
- Caching & asynchronous messaging for scalability (ElastiCache, SNS).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Tier
    subgraph "Client Tier"
        Browser["Browser (Static UI)"]:::frontend
        GruntServer["Grunt Dev Server"]:::frontend
        UI["UI"]:::frontend
        UI_src["UI/src"]:::frontend
        UI_test["UI/test"]:::frontend
        RobotTests["RobotProjectTest"]:::frontend
    end

    %% API Tier
    subgraph "API Tier"
        ECS["ECS Fargate Task"]:::api
        ScalatraContainer["Scalatra Container"]:::api
        SBootstrap["ScalatraBootstrap.scala"]:::api
        DServer["DigiroadServer.scala"]:::api
        PServer["ProductionServer.scala"]:::api
        API_OT["digiroad2-api-oth"]:::api
        API_Common["digiroad2-api-common"]:::api
        GeoLib["digiroad2-geo"]:::api
    end

    %% Data Tier
    subgraph "Data Tier"
        Postgres["RDS Postgres / Oracle"]:::db
        Redis["ElastiCache Redis"]:::db
        S3Bucket["S3 Buckets"]:::db
    end

    %% Persistence Modules
    subgraph "Persistence Modules"
        OracleMod["digiroad2-oracle"]:::db
        LocalPostGIS["aws/local-dev/postgis"]:::db
        EnablePostGIS["enable-postgis.sql"]:::db
    end

    %% Infrastructure & Services
    subgraph "Infrastructure & Services"
        ALB["ALB"]:::infra
        IAM["IAM Roles\nParameter Store"]:::infra
        CloudWatch["CloudWatch Logs & Metrics"]:::infra
        SNS["SNS Topics"]:::infra
        BatchSystem["AWS Batch"]:::infra
        Lambda["AWS Lambda"]:::infra
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        GitHub["GitHub"]:::cicd
        CodeBuild["CodeBuild"]:::cicd
        CodePipeline["CodePipeline"]:::cicd
        ECR["ECR"]:::cicd
        CodeArtifact["CodeArtifact"]:::cicd
    end

    %% External Integrations
    subgraph "External Integrations"
        VVH["VVH API"]:::ext
        VKM["VKM API"]:::ext
        GoogleMaps["Google Maps"]:::ext
    end

    %% Local Dev & Docs
    subgraph "Local Dev & Docs"
        IdeaConfigs["aws/local-dev/idea-run-configurations"]:::infra
        EnvProps["conf/env.properties"]:::infra
        Gruntfile["gruntfile.js & package.json"]:::infra
        SBTBuild["project/ & build.scala"]:::infra
        Manual["UI/manual"]:::frontend
        README["README.md"]:::infra
    end

    %% Batch & Lambda Files
    subgraph "Batch & Lambda Config"
        BatchYAML["batchSystem.yaml"]:::infra
        LambdaYAML["batchLambda.yaml"]:::infra
    end

    %% Cache Integration
    subgraph "Cache Integration"
        CacheYAML["cache.yaml"]:::infra
        CacheClient["CacheClient.scala"]:::api
    end

    %% Connections
    Browser -->|HTTP| ALB
    GruntServer -->|Serves UI| Browser
    ALB -->|Routes /api/*| ECS
    ALB -->|Routes /static| S3Bucket
    ECS -->|JDBC| Postgres
    ECS -->|TCP| Redis
    ECS -->|HTTPS| S3Bucket
    ECS -->|HTTPS| VVH
    ECS -->|HTTPS| VKM
    ECS -->|HTTPS| GoogleMaps
    GitHub -->|push| CodeBuild
    CodeBuild -->|build images| ECR
    CodeBuild -->|publish packages| CodeArtifact
    CodePipeline -->|deploy| ECS
    CodePipeline -->|deploy infra| ALB
    BatchSystem -->|invoke| Lambda
    Lambda -->|JDBC| Postgres

    %% Detailed Modules Links
    ECS --> ScalatraContainer
    ScalatraContainer --> SBootstrap
    ScalatraContainer --> DServer
    ScalatraContainer --> PServer
    ScalatraContainer --> API_OT
    ScalatraContainer --> API_Common
    ScalatraContainer --> GeoLib
    ECS --> CacheClient
    Postgres --> OracleMod
    Postgres --> LocalPostGIS
    Postgres --> EnablePostGIS

    %% Click Events
    click UI "https://github.com/finnishtransportagency/digiroad2/tree/master/UI"
    click UI_src "https://github.com/finnishtransportagency/digiroad2/tree/master/UI/src"
    click UI_test "https://github.com/finnishtransportagency/digiroad2/tree/master/UI/test"
    click RobotTests "https://github.com/finnishtransportagency/digiroad2/tree/master/RobotProjectTest"
    click SBootstrap "https://github.com/finnishtransportagency/digiroad2/blob/master/src/main/scala/ScalatraBootstrap.scala"
    click DServer "https://github.com/finnishtransportagency/digiroad2/blob/master/src/main/scala/fi/liikennevirasto/digiroad2/DigiroadServer.scala"
    click PServer "https://github.com/finnishtransportagency/digiroad2/blob/master/src/main/scala/fi/liikennevirasto/digiroad2/ProductionServer.scala"
    click API_OT "https://github.com/finnishtransportagency/digiroad2/tree/master/digiroad2-api-oth"
    click API_Common "https://github.com/finnishtransportagency/digiroad2/tree/master/digiroad2-api-common"
    click GeoLib "https://github.com/finnishtransportagency/digiroad2/tree/master/digiroad2-geo"
    click OracleMod "https://github.com/finnishtransportagency/digiroad2/tree/master/digiroad2-oracle"
    click LocalPostGIS "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/local-dev/postgis"
    click EnablePostGIS "https://github.com/finnishtransportagency/digiroad2/blob/master/aws/rds/enable-postgis.sql"
    click ALB "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/cloud-formation/fargateService"
    click IAM "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/cloud-formation/parameter-store"
    click CloudWatch "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/cloud-formation/cicd"
    click SNS "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/cloud-formation/sns"
    click BatchSystem "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/cloud-formation/batchSystem"
    click Lambda "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/cloud-formation/batchSystem"
    click ECR "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/cloud-formation/ecr"
    click CodeArtifact "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/cloud-formation/cicd/codeArtifact"
    click CodeBuild "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/cloud-formation/cicd"
    click CodePipeline "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/cloud-formation/cicd/dev"
    click S3Bucket "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/cloud-formation/s3"
    click CacheYAML "https://github.com/finnishtransportagency/digiroad2/blob/master/aws/cloud-formation/cache/cache.yaml"
    click IdeaConfigs "https://github.com/finnishtransportagency/digiroad2/tree/master/aws/local-dev/idea-run-configurations"
    click EnvProps "https://github.com/finnishtransportagency/digiroad2/blob/master/conf/env.properties"
    click Gruntfile "https://github.com/finnishtransportagency/digiroad2/blob/master/gruntfile.js"
    click SBTBuild "https://github.com/finnishtransportagency/digiroad2/tree/master/project/"
    click Manual "https://github.com/finnishtransportagency/digiroad2/tree/master/UI/manual"
    click README "https://github.com/finnishtransportagency/digiroad2/blob/master/README.md"
    click BatchYAML "https://github.com/finnishtransportagency/digiroad2/blob/master/aws/cloud-formation/batchSystem/batchSystem.yaml"
    click LambdaYAML "https://github.com/finnishtransportagency/digiroad2/blob/master/aws/cloud-formation/batchSystem/batchLambda/batchLambda.yaml"
    click CacheClient "https://github.com/finnishtransportagency/digiroad2/blob/master/digiroad2-oracle/src/main/scala/fi/liikennevirasto/digiroad2/client/CacheClient.scala"
    click VVH "https://github.com/finnishtransportagency/digiroad2/blob/master/digiroad2-oracle/src/main/scala/fi/liikennevirasto/digiroad2/client/RoadLinkClient.scala"
    click VKM "https://github.com/finnishtransportagency/digiroad2/blob/master/digiroad2-oracle/src/main/scala/fi/liikennevirasto/digiroad2/client/VKMClient.scala"
    click GeoLib "https://github.com/finnishtransportagency/digiroad2/tree/master/digiroad2-geo"
    click API_Common "https://github.com/finnishtransportagency/digiroad2/tree/master/digiroad2-api-common/src/main/scala/fi/liikennevirasto/digiroad2/vallu"
    click Gruntfile "https://github.com/finnishtransportagency/digiroad2/blob/master/package.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
    classDef api fill:#d4edda,stroke:#155724,color:#155724
    classDef db fill:#fff3cd,stroke:#856404,color:#856404
    classDef infra fill:#e2e3e5,stroke:#383d41,color:#383d41
    classDef cicd fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef ext fill:#e0d9ff,stroke:#4b0082,color:#4b0082
```
