Backend microservices and Server Technical Architecture overview

Technical Architecture Overview

Date: 2026-02-22

System Architecture Diagram

graph TD
    subgraph Host["Host Machine (Localhost)"]
        User(("User / Client"))

        subgraph Local_Process["Digital-Assistant-Server"]
            Quarkus["Quarkus Backend<br/>Port: 11081"]
        end

        subgraph Docker_Swarm["Digital_Assistant_microServices (Docker)"]
            subgraph Network["uda-network"]
                Nginx["Nginx Gateway<br/>Host Ports: 80, 443"]
                
                Keycloak["Keycloak (Auth)<br/>Host Ports: 8080, 8443, 9990<br/>Internal: 8443"]
                
                NestJS["NestJS Admin<br/>Host Port: 3003<br/>Internal: 3003"]
                
                Postgres[("Postgres DB<br/>(Keycloak Data)<br/>Host Port: 5432")]
                
                MariaDB[("MariaDB<br/>(Quarkus Data)<br/>Host Port: 3306")]
                
                Elastic[("Elasticsearch<br/>(Search Index)<br/>Host Port: 9200")]
            end
        end
    end

    %% User Ingress
    User -->|"HTTPS/443 <br/> *.nistapp"| Nginx
    User -->|"HTTP/11081 <br/> Direct API Access"| Quarkus

    %% Nginx Routing
    Nginx -->|"Proxy Pass <br/> keycloak.nistapp"| Keycloak
    Nginx -->|"Proxy Pass <br/> authenticate.nistapp"| NestJS
    Nginx -->|"Serves Static <br/> udan-sdk.nistapp"| SDK_Files["Static SDK Files"]
    Nginx -->|"Serves Static <br/> signup.nistapp"| Signup_Files["Static Signup Files"]

    %% Service Interactions
    Quarkus -->|"JDBC"| MariaDB
    Quarkus -->|"REST/Transport"| Elastic
    Quarkus -.->|"OIDC Auth <br/> (Configured to External/Local)"| Keycloak

    Keycloak -->|"Persists Data"| Postgres
    NestJS -.->|"Admin API"| Keycloak

    %% Internal Docker Network links
    Keycloak -.- Postgres
    NestJS -.- Keycloak

    style Docker_Swarm fill:#f9f9f9,stroke:#333,stroke-dasharray: 5

Loading

Service Configuration & Port Mapping

1. Digital_Assistant_microServices (Docker Swarm)

These services are orchestrated via start-all-dev-dockers.sh and run on the uda-network bridge network.

Service	Container Name	Host Port (Localhost)	Internal Port	Config File
Nginx (Gateway)	nginx-server-udan	80, 443	80, 443	docker/nginx/docker-compose-nginx.yaml
Keycloak (Auth)	keycloak_local	8080 (HTTP) 8443 (HTTPS) 9990 (Admin)	8080, 8443	docker/keycloak/docker-compose-keycloak.yaml
NestJS Admin	token-service-local	3003	3003	nestjs-keycloak-admin/docker-compose-nestjs.yaml
MariaDB	mariadb-udan	3306	3306	docker/mariadb/docker-compose-mariadb.yaml
Postgres	postgres-udan	5432	5432	docker/postgres/docker-compose-postgres.yaml
Elasticsearch	elasticsearch	9200	9200	docker/elasticsearch/docker-compose-elasticsearch.yaml

2. Digital-Assistant-Server (Local Process)

This service runs natively on the host machine.

Service	Technology	Port	Configuration File
Backend Server	Quarkus (Java)	11081	src/main/resources/application.properties

Key Components Description

1. Nginx (Gateway):

   • Serves as the primary ingress controller listening on ports 80 and 443.
   • Handles SSL termination and routing for domains *.nistapp.
   • Routes traffic to internal services:
     • keycloak.nistapp -> Keycloak Container
     • authenticate.nistapp -> NestJS Admin Container
     • udan-sdk.nistapp -> Static SDK Files
     • signup.nistapp -> Static Signup Files

2. Quarkus (Backend):

   • The core application server running locally.
   • Configured to run on port 11081 to avoid conflict with Keycloak's default port 8080.
   • Connects directly to localhost ports for data services (MariaDB:3306, Elasticsearch:9200).

3. Keycloak (Identity Provider):

   • Manages user authentication and authorization.
   • Accessible directly via localhost:8080/8443 or through the Nginx proxy.
   • Persists data to a dedicated Postgres database.

4. Databases:

   • Postgres (5432): Dedicated persistence layer for Keycloak.
   • MariaDB (3306): Primary persistence layer for the Quarkus application.
   • Elasticsearch (9200): Search engine used by the Quarkus backend.