# n-xus-ll/web-app architecture

> Architecture diagram of the GitHub repository n-xus-ll/web-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/n-xus-ll/web-app
- Repository: https://github.com/n-xus-ll/web-app

## Overview

1. This repository is a full-stack web application with three main runtimes: a React/Vite frontend, a Kotlin/Ktor backend, and a PostgreSQL database. The backend is organized as a multi-module Gradle project under `backend/ktor-backend`.

2. The frontend lives in `frontend/` and is a single-page app built with React. It contains page-level views for items, loans, users, locations, statistics, profiles, login/register, and a map page. The UI is split into reusable components, a map context, and service wrappers that call backend APIs.

3. The backend `server` module is the main application runtime. It uses Ktor for HTTP routing, serialization, logging, and likely WebSocket/RPC support. Entry points and bootstrap are in `server/src/main/kotlin/main.kt`, `Routing.kt`, `Http.kt`, `Serialization.kt`, and `Resources.kt`.

4. The backend is layered: routes/controllers live in `routes/` and `features/*/*Routes.kt`, business logic is in feature services such as `LoansService`, and persistence is abstracted through `repository/` plus `database/` entity/mapper/table definitions. This is a classic API → service → repository → database flow.

5. The primary business domains are items, loans, users, and locations. Each domain has its own route/model files, and there are database tables and DTO/entity classes for items, locations, users, and lookup/reference data like categories, item conditions, and damage policies.

6. Authentication is handled on the backend in `auth/` with JWT support. The frontend has dedicated auth services and protected routing (`PrivateRoute.jsx`), so the app likely uses token-based session state passed between client and server.

7. PostgreSQL is the persistent store. The schema is defined in `database/schema.sql` and seeded via `database/seed.sql`, while the backend’s `database/tables/*` and `database/*Mapper.kt` files map the relational schema into application objects.

8. There is a Kotlin DSL subsystem in `server/src/main/kotlin/dsl/` with lexer, parser, AST, semantic analyzer, interpreter, and GeoJSON export. That means the backend accepts a custom query or scripting language, validates it, executes it, and can convert results into geospatial output.

9. Spatial/geographic data is a first-class concern. The backend has geo-point models, parsers/formatters, GeoJSON utilities, and a `MapPage` plus geocoding service on the frontend. This suggests map-based item/location visualization and location lookup are key features.

10. The `core` module provides shared contract code: service interfaces, request/response models, and common types such as `GeoPoint`, `LoginRequest`, and `UserResponse`. This module is shared between client and server to keep API/data contracts aligned.

11. The `client` module is a Kotlin RPC client built around the shared core. Its presence, along with `kotlinx-rpc` dependencies and `Rpc.kt` files on both client and server, indicates a typed RPC layer in addition to or alongside the HTTP API.

12. Operationally, the repo is containerized. There are Dockerfiles for both frontend and backend, Docker Compose files at the repo root, and a GitHub Actions workflow for deployment. The frontend also uses Nginx for production serving.

13. The backend includes tests for HTTP/RPC behavior and the DSL interpreter. That implies the more complex boundaries being validated are the API layer, remote contract layer, and custom query language rather than the React UI.

14. For diagramming, the core data flow is: browser UI → frontend service layer → backend routes/RPC → domain services → repositories/ORM tables → PostgreSQL, with side paths for auth/JWT, DSL execution, and geospatial conversion/GeoJSON output.

Main entry points: [`backend/ktor-backend/server/src/main/kotlin/Routing.kt`](https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/Routing.kt) (Routing), [`backend/ktor-backend/server/src/main/kotlin/repository`](https://github.com/n-xus-ll/web-app/tree/main/backend/ktor-backend/server/src/main/kotlin/repository) (Repositories), [`backend/ktor-backend/server/src/main/kotlin/main.kt`](https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/main.kt) (Server main), [`docker-compose.yml`](https://github.com/n-xus-ll/web-app/blob/main/docker-compose.yml) (Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app["App shell<br/>React SPA<br/>[App.jsx]"]
  node_pages["Pages<br/>UI views"]
  node_ui["Components<br/>UI widgets"]
  node_services["Services<br/>API clients"]
  node_mapctx(("Map context<br/>state context<br/>[MapContext.jsx]"))
end

subgraph group_backend["Backend"]
  node_main["Server main<br/>Ktor entrypoint<br/>[main.kt]"]
  node_http["HTTP setup<br/>Ktor config<br/>[Http.kt]"]
  node_routing["Routing<br/>API wiring<br/>[Routing.kt]"]
  node_auth["Auth<br/>[AuthService.kt]"]
  node_items["Items<br/>feature module<br/>[ItemRoutes.kt]"]
  node_loans["Loans<br/>feature module<br/>[LoansService.kt]"]
  node_users["Users<br/>feature module<br/>[UserModel.kt]"]
  node_locations["Locations<br/>feature module<br/>[LocationRoutes.kt]"]
  node_dsl["DSL engine<br/>query runtime"]
  node_repo["Repositories<br/>data access"]
  node_db[("ORM tables<br/>database mapping")]
  node_geo["Spatial utils<br/>geo helpers<br/>[GeoJson.kt]"]
end

subgraph group_shared["Shared Contracts"]
  node_core["Core contracts<br/>shared models"]
  node_client["RPC client<br/>typed client"]
end

subgraph group_ops["Ops"]
  node_compose["Compose<br/>container orchestration<br/>[docker-compose.yml]"]
end

subgraph group_data["Data"]
  node_postgres[("PostgreSQL<br/>relational store<br/>[schema.sql]")]
end

node_app -->|"navigates to"| node_pages
node_app -->|"uses"| node_ui
node_pages -->|"calls"| node_services
node_pages -->|"shares state"| node_mapctx
node_ui -.->|"invokes"| node_services
node_services -.->|"typed RPC"| node_client
node_main -->|"configures"| node_http
node_main -->|"registers"| node_routing
node_main -->|"enables"| node_auth
node_routing -->|"mounts"| node_items
node_routing -->|"mounts"| node_loans
node_routing -->|"mounts"| node_users
node_routing -->|"mounts"| node_locations
node_routing -->|"mounts"| node_dsl
node_auth -.->|"shares models"| node_core
node_items -->|"reads/writes"| node_repo
node_loans -->|"reads/writes"| node_repo
node_users -->|"reads/writes"| node_repo
node_locations -->|"reads/writes"| node_repo
node_repo -->|"maps to"| node_db
node_db -->|"persists in"| node_postgres
node_dsl -->|"queries through"| node_repo
node_dsl -.->|"exports"| node_geo
node_geo -.->|"supports"| node_db
node_client -->|"depends on"| node_core
node_compose -.->|"starts"| node_main
node_compose -.->|"starts"| node_app
node_compose -.->|"starts"| node_postgres

click node_app "https://github.com/n-xus-ll/web-app/blob/main/frontend/src/App.jsx"
click node_pages "https://github.com/n-xus-ll/web-app/tree/main/frontend/src/pages"
click node_ui "https://github.com/n-xus-ll/web-app/tree/main/frontend/src/components"
click node_services "https://github.com/n-xus-ll/web-app/tree/main/frontend/src/services"
click node_mapctx "https://github.com/n-xus-ll/web-app/blob/main/frontend/src/contexts/MapContext.jsx"
click node_main "https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/main.kt"
click node_http "https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/Http.kt"
click node_routing "https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/Routing.kt"
click node_auth "https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/auth/AuthService.kt"
click node_items "https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/features/items/ItemRoutes.kt"
click node_loans "https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/features/loans/LoansService.kt"
click node_users "https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/features/users/UserModel.kt"
click node_locations "https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/routes/LocationRoutes.kt"
click node_dsl "https://github.com/n-xus-ll/web-app/tree/main/backend/ktor-backend/server/src/main/kotlin/dsl"
click node_repo "https://github.com/n-xus-ll/web-app/tree/main/backend/ktor-backend/server/src/main/kotlin/repository"
click node_db "https://github.com/n-xus-ll/web-app/tree/main/backend/ktor-backend/server/src/main/kotlin/database"
click node_geo "https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/features/common/spatial/GeoJson.kt"
click node_core "https://github.com/n-xus-ll/web-app/tree/main/backend/ktor-backend/core/src/commonMain/kotlin"
click node_client "https://github.com/n-xus-ll/web-app/tree/main/backend/ktor-backend/client/src/commonMain/kotlin"
click node_postgres "https://github.com/n-xus-ll/web-app/blob/main/database/schema.sql"
click node_compose "https://github.com/n-xus-ll/web-app/blob/main/docker-compose.yml"

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_app,node_pages,node_ui,node_services,node_mapctx toneBlue
class node_main,node_http,node_routing,node_auth,node_items,node_loans,node_users,node_locations,node_dsl,node_repo,node_db,node_geo toneAmber
class node_core,node_client toneMint
class node_compose toneRose
class node_postgres toneIndigo
```

## Components

### Frontend

React/Vite SPA and browser-side services

- [App shell](https://github.com/n-xus-ll/web-app/blob/main/frontend/src/App.jsx): React SPA · Top-level client application and route composition · `frontend/src/App.jsx`
- [Pages](https://github.com/n-xus-ll/web-app/tree/main/frontend/src/pages): UI views · Page-level screens for items, loans, users, auth, map, and stats · `frontend/src/pages`
- [Components](https://github.com/n-xus-ll/web-app/tree/main/frontend/src/components): UI widgets · Reusable presentation components and workflows · `frontend/src/components`
- [Services](https://github.com/n-xus-ll/web-app/tree/main/frontend/src/services): API clients · Frontend service wrappers for backend APIs and geocoding · `frontend/src/services`
- [Map context](https://github.com/n-xus-ll/web-app/blob/main/frontend/src/contexts/MapContext.jsx): state context · Shared browser state for map interactions · `frontend/src/contexts/MapContext.jsx`

### Backend

Ktor server, domain layers, and API/runtime infrastructure

- [Server main](https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/main.kt): Ktor entrypoint · Bootstrap, routing, serialization, and runtime wiring · `backend/ktor-backend/server/src/main/kotlin/main.kt`
- [HTTP setup](https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/Http.kt): Ktor config · HTTP server configuration and middleware setup · `backend/ktor-backend/server/src/main/kotlin/Http.kt`
- [Routing](https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/Routing.kt): API wiring · Top-level route registration for server features · `backend/ktor-backend/server/src/main/kotlin/Routing.kt`
- [Auth](https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/auth/AuthService.kt): JWT auth · Authentication service and JWT configuration · `backend/ktor-backend/server/src/main/kotlin/auth/AuthService.kt`
- [Items](https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/features/items/ItemRoutes.kt): feature module · Item domain routes, models, and reference data · `backend/ktor-backend/server/src/main/kotlin/features/items/ItemRoutes.kt`
- [Loans](https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/features/loans/LoansService.kt): feature module · Loan workflow, service logic, DTOs, and routes · `backend/ktor-backend/server/src/main/kotlin/features/loans/LoansService.kt`
- [Users](https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/features/users/UserModel.kt): feature module · User domain models and routes · `backend/ktor-backend/server/src/main/kotlin/features/users/UserModel.kt`
- [Locations](https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/routes/LocationRoutes.kt): feature module · Location routes and models · `backend/ktor-backend/server/src/main/kotlin/routes/LocationRoutes.kt`
- [DSL engine](https://github.com/n-xus-ll/web-app/tree/main/backend/ktor-backend/server/src/main/kotlin/dsl): query runtime · Lexer, parser, semantic analysis, interpreter, and GeoJSON export · `backend/ktor-backend/server/src/main/kotlin/dsl`
- [Repositories](https://github.com/n-xus-ll/web-app/tree/main/backend/ktor-backend/server/src/main/kotlin/repository): data access · Persistence layer for items, locations, users, and DSL queries · `backend/ktor-backend/server/src/main/kotlin/repository`
- [ORM tables](https://github.com/n-xus-ll/web-app/tree/main/backend/ktor-backend/server/src/main/kotlin/database): database mapping · Entity, mapper, and table definitions for relational persistence · `backend/ktor-backend/server/src/main/kotlin/database`
- [Spatial utils](https://github.com/n-xus-ll/web-app/blob/main/backend/ktor-backend/server/src/main/kotlin/features/common/spatial/GeoJson.kt): geo helpers · Geo-point parsing, formatting, and GeoJSON helpers · `backend/ktor-backend/server/src/main/kotlin/features/common/spatial/GeoJson.kt`

### Shared Contracts

Common Kotlin code used by client and server

- [Core contracts](https://github.com/n-xus-ll/web-app/tree/main/backend/ktor-backend/core/src/commonMain/kotlin): shared models · Common request/response models and service contracts · `backend/ktor-backend/core/src/commonMain/kotlin`
- [RPC client](https://github.com/n-xus-ll/web-app/tree/main/backend/ktor-backend/client/src/commonMain/kotlin): typed client · Kotlin RPC client built on shared contracts · `backend/ktor-backend/client/src/commonMain/kotlin`

### Ops

Containerization and deployment assets

- [Compose](https://github.com/n-xus-ll/web-app/blob/main/docker-compose.yml): container orchestration · Local runtime wiring for frontend, backend, and database · `docker-compose.yml`

### Data

PostgreSQL schema and seed data

- [PostgreSQL](https://github.com/n-xus-ll/web-app/blob/main/database/schema.sql): relational store · Primary persistent database · `database/schema.sql`

## Connections

- App shell → Pages: navigates to · App shell renders page-level routes
- App shell → Components: uses · App composes reusable UI widgets
- Pages → Services: calls · Screens fetch and mutate data through service wrappers
- Pages → Map context: shares state · Map-related screens use common map state
- Components → Services: invokes · Interactive widgets trigger service calls
- Services → RPC client: typed RPC · Frontend service layer aligns with shared client contracts
- Server main → HTTP setup: configures · Bootstraps HTTP server behavior
- Server main → Routing: registers · Installs top-level routes
- Server main → Auth: enables · Wires authentication into runtime
- Routing → Items: mounts · Routes requests into item feature module
- Routing → Loans: mounts · Routes requests into loan feature module
- Routing → Users: mounts · Routes requests into user feature module
- Routing → Locations: mounts · Routes requests into location feature module
- Routing → DSL engine: mounts · Routes DSL/query execution endpoints
- Auth → Core contracts: shares models · Authentication uses shared request/response types
- Items → Repositories: reads/writes · Item feature persists through repositories
- Loans → Repositories: reads/writes · Loan workflows depend on persistence layer
- Users → Repositories: reads/writes · User feature uses repository access
- Locations → Repositories: reads/writes · Location feature uses repository access
- Repositories → ORM tables: maps to · Repositories operate over entities and tables
- ORM tables → PostgreSQL: persists in · ORM mapping targets PostgreSQL schema
- DSL engine → Repositories: queries through · DSL interpreter executes against repository-backed data
- DSL engine → Spatial utils: exports · DSL results can be converted to GeoJSON and spatial output
- Spatial utils → ORM tables: supports · Spatial helpers align with stored geo data
- RPC client → Core contracts: depends on · Typed RPC client uses shared contracts
- Compose → Server main: starts · Compose brings up backend runtime
- Compose → App shell: starts · Compose serves frontend runtime
- Compose → PostgreSQL: starts · Compose provisions PostgreSQL