# winlu2303/hackathon-max-2026 architecture

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

- Interactive diagram: https://gitdiagram.com/winlu2303/hackathon-max-2026
- Repository: https://github.com/winlu2303/hackathon-max-2026

## Overview

Дом в Порядке is a MAX chat bot for finding a building’s management company and managing emergency and repair requests. Residents register a role and address, select a matching company (or private-sector status), then submit requests, review their status, and close them. MAX webhooks pass through the Go gateway and NATS to Java’s dialog handler; Java also exposes REST endpoints and stores records in PostgreSQL, with Redis for dialog state. The README documents monthly reminders and contact lookup. Several links reflect documented architecture or SOURCE INDEX references; unsampled details are not inferred.

Main entry points: [`java-core/src/main/java/ru/domvporyadke/max/MessageHandler.java`](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/max/MessageHandler.java) (Dialog handler), [`go-gateway/main.go`](https://github.com/winlu2303/hackathon-max-2026/blob/main/go-gateway/main.go) (Go gateway), [`java-core/src/main/java/ru/domvporyadke/max/NatsListener.java`](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/max/NatsListener.java) (NATS listener), [`java-core/src/main/java/ru/domvporyadke/max/MAXApiClient.java`](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/max/MAXApiClient.java) (MAX API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Webhook ingress"]
  node_gateway["Go gateway<br/>[main.go]"]
  node_nats["NATS events"]
  node_listener["NATS listener<br/>[NatsListener.java]"]
end

subgraph group_dialog["Bot dialogue"]
  node_handler["Dialog handler"]
  node_fsm["Dialog state<br/>[FSMService.java]"]
  node_max_api["MAX API client<br/>[MAXApiClient.java]"]
  node_company_search["Company lookup"]
  node_user_service["MAX user profiles"]
  node_monthly_ping["Monthly reminders"]
end

subgraph group_requests["Request management"]
  node_emergency["Emergency requests"]
  node_repair["Repair requests"]
  node_request_api["Request REST API"]
  node_emergency_api["Emergency REST API"]
  node_buildings_api["Buildings REST API"]
end

subgraph group_persistence["State and storage"]
  node_pg[("PostgreSQL")]
  node_redis[("Redis")]
end

node_resident(("Resident"))
node_max_platform["MAX platform"]
node_cloudpub["Cloudpub proxy"]

node_resident -->|"sends chat"| node_max_platform
node_max_platform -->|"webhook"| node_cloudpub
node_cloudpub -->|"proxies webhook"| node_gateway
node_gateway -->|"publishes events"| node_nats
node_gateway -.->|"HTTP requests"| node_listener
node_nats -->|"delivers events"| node_listener
node_listener -->|"dispatches updates"| node_handler
node_handler -->|"uses state"| node_fsm
node_handler -->|"sends replies"| node_max_api
node_max_api -->|"calls bot API"| node_max_platform
node_handler -->|"searches companies"| node_company_search
node_handler -->|"manages profiles"| node_user_service
node_handler -->|"creates and closes"| node_emergency
node_handler -->|"creates and closes"| node_repair
node_emergency_api -->|"routes requests"| node_emergency
node_request_api -->|"routes requests"| node_repair
node_buildings_api -.->|"looks up buildings"| node_company_search
node_emergency -->|"persists records"| node_pg
node_repair -->|"persists records"| node_pg
node_user_service -->|"stores profiles"| node_pg
node_company_search -->|"queries companies"| node_pg
node_fsm -->|"stores dialogue state"| node_redis
node_monthly_ping -->|"reads and updates users"| node_pg
node_monthly_ping -->|"sends reminders"| node_max_api

click node_gateway "https://github.com/winlu2303/hackathon-max-2026/blob/main/go-gateway/main.go"
click node_listener "https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/max/NatsListener.java"
click node_handler "https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/max/MessageHandler.java"
click node_fsm "https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/max/FSMService.java"
click node_max_api "https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/max/MAXApiClient.java"
click node_company_search "https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/repository/ManagementCompanyRepository.java"
click node_user_service "https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/service/MaxUserService.java"
click node_emergency "https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/service/EmergencyService.java"
click node_repair "https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/service/ServiceRequestService.java"
click node_request_api "https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/web/ServiceRequestController.java"
click node_emergency_api "https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/web/EmergencyController.java"
click node_buildings_api "https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/web/BuildingsController.java"
click node_monthly_ping "https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/service/MonthlyPingService.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway,node_nats,node_listener toneBlue
class node_handler,node_fsm,node_max_api,node_company_search,node_user_service,node_monthly_ping toneAmber
class node_emergency,node_repair,node_request_api,node_emergency_api,node_buildings_api toneMint
class node_pg,node_redis toneRose
class node_resident,node_max_platform,node_cloudpub toneIndigo
```

## Components

### Webhook ingress

- [Go gateway](https://github.com/winlu2303/hackathon-max-2026/blob/main/go-gateway/main.go): `go-gateway/main.go`
- **NATS events**
- [NATS listener](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/max/NatsListener.java): `java-core/src/main/java/ru/domvporyadke/max/NatsListener.java`

### Bot dialogue

- [Dialog handler](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/max/MessageHandler.java): `java-core/src/main/java/ru/domvporyadke/max/MessageHandler.java`
- [Dialog state](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/max/FSMService.java): `java-core/src/main/java/ru/domvporyadke/max/FSMService.java`
- [MAX API client](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/max/MAXApiClient.java): `java-core/src/main/java/ru/domvporyadke/max/MAXApiClient.java`
- [Company lookup](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/repository/ManagementCompanyRepository.java): `java-core/src/main/java/ru/domvporyadke/repository/ManagementCompanyRepository.java`
- [MAX user profiles](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/service/MaxUserService.java): `java-core/src/main/java/ru/domvporyadke/service/MaxUserService.java`
- [Monthly reminders](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/service/MonthlyPingService.java): `java-core/src/main/java/ru/domvporyadke/service/MonthlyPingService.java`

### Request management

- [Emergency requests](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/service/EmergencyService.java): `java-core/src/main/java/ru/domvporyadke/service/EmergencyService.java`
- [Repair requests](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/service/ServiceRequestService.java): `java-core/src/main/java/ru/domvporyadke/service/ServiceRequestService.java`
- [Request REST API](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/web/ServiceRequestController.java): `java-core/src/main/java/ru/domvporyadke/web/ServiceRequestController.java`
- [Emergency REST API](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/web/EmergencyController.java): `java-core/src/main/java/ru/domvporyadke/web/EmergencyController.java`
- [Buildings REST API](https://github.com/winlu2303/hackathon-max-2026/blob/main/java-core/src/main/java/ru/domvporyadke/web/BuildingsController.java): `java-core/src/main/java/ru/domvporyadke/web/BuildingsController.java`

### State and storage

- **PostgreSQL**
- **Redis**

### Other components

- **Resident**
- **MAX platform**
- **Cloudpub proxy**

## Connections

- Resident → MAX platform: sends chat (evidence: `README.md`)
- MAX platform → Cloudpub proxy: webhook (evidence: `README.md`)
- Cloudpub proxy → Go gateway: proxies webhook (evidence: `README.md`)
- Go gateway → NATS events: publishes events (evidence: `README.md`)
- Go gateway → NATS listener: HTTP requests
- NATS events → NATS listener: delivers events (evidence: `README.md`)
- NATS listener → Dialog handler: dispatches updates (evidence: `java-core/src/main/java/ru/domvporyadke/max/NatsListener.java`)
- Dialog handler → Dialog state: uses state (evidence: `java-core/src/main/java/ru/domvporyadke/max/MessageHandler.java`)
- Dialog handler → MAX API client: sends replies (evidence: `java-core/src/main/java/ru/domvporyadke/max/MessageHandler.java`)
- MAX API client → MAX platform: calls bot API (evidence: `README.md`)
- Dialog handler → Company lookup: searches companies (evidence: `java-core/src/main/java/ru/domvporyadke/max/MessageHandler.java`)
- Dialog handler → MAX user profiles: manages profiles (evidence: `java-core/src/main/java/ru/domvporyadke/max/MessageHandler.java`)
- Dialog handler → Emergency requests: creates and closes (evidence: `java-core/src/main/java/ru/domvporyadke/max/MessageHandler.java`)
- Dialog handler → Repair requests: creates and closes (evidence: `java-core/src/main/java/ru/domvporyadke/max/MessageHandler.java`)
- Emergency REST API → Emergency requests: routes requests (evidence: `java-core/src/main/java/ru/domvporyadke/web/EmergencyController.java`)
- Request REST API → Repair requests: routes requests (evidence: `java-core/src/main/java/ru/domvporyadke/web/ServiceRequestController.java`)
- Buildings REST API → Company lookup: looks up buildings
- Emergency requests → PostgreSQL: persists records (evidence: `README.md`)
- Repair requests → PostgreSQL: persists records (evidence: `README.md`)
- MAX user profiles → PostgreSQL: stores profiles (evidence: `README.md`)
- Company lookup → PostgreSQL: queries companies (evidence: `README.md`)
- Dialog state → Redis: stores dialogue state (evidence: `README.md`)
- Monthly reminders → PostgreSQL: reads and updates users (evidence: `java-core/src/main/java/ru/domvporyadke/service/MonthlyPingService.java`)
- Monthly reminders → MAX API client: sends reminders (evidence: `java-core/src/main/java/ru/domvporyadke/service/MonthlyPingService.java`)
