# abuba111/openwatermap architecture

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

## Overview

OpenWaterMap is a water-quality mapping and community reporting service. Users browse approved water points and their measurements; authenticated contributors submit or update points, while trusted reviewers verify pending submissions. The backend also supports account and role management, comments, and photo/certificate uploads. The graph follows the HTTP routes and calls shown in the sampled entrypoint and handlers. Some handler/database operations are omitted from excerpts, so their connections are not inferred; the README supplied no capability details.

Main entry points: [`openwatermap/backend/main.go`](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/main.go) (HTTP routing), [`openwatermap/backend/database/sqlite.go`](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/database/sqlite.go) (PostgreSQL access), [`openwatermap/backend/handlers/auth.go`](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/handlers/auth.go) (Account endpoints), [`openwatermap/backend/handlers/media.go`](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/handlers/media.go) (Comments and uploads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API runtime"]
  node_runtime["HTTP routing<br/>[main.go]"]
  node_health["Health check<br/>[health.go]"]
  node_config["Runtime config<br/>[config.go]"]
end

subgraph group_water["Water reporting"]
  node_water_handler["Point endpoints<br/>[water.go]"]
  node_water_model["Water rules<br/>[water.go]"]
end

subgraph group_identity["Identity and access"]
  node_auth_handler["Account endpoints<br/>[auth.go]"]
  node_auth_middleware["JWT and roles<br/>[auth_middleware.go]"]
  node_user_model["User and roles<br/>[user.go]"]
end

subgraph group_community["Community media"]
  node_media_handler["Comments and uploads<br/>[media.go]"]
  node_comment_model["Comment and photo data<br/>[comment.go]"]
end

subgraph group_persistence["Persistence"]
  node_db[("PostgreSQL access<br/>[sqlite.go]")]
  node_user_db[("User records<br/>[users.go]")]
  node_media_db[("Comments and photo records<br/>[comments.go]")]
  node_migrations["Schema migrations<br/>[migrate.go]"]
end

node_users(("Map users"))

node_users -->|"calls API"| node_runtime
node_runtime -->|"loads settings"| node_config
node_runtime -->|"opens database"| node_db
node_runtime -->|"routes points"| node_water_handler
node_runtime -->|"routes auth"| node_auth_handler
node_runtime -->|"routes media"| node_media_handler
node_runtime -->|"routes health"| node_health
node_runtime -->|"applies guards"| node_auth_middleware
node_water_handler -->|"reads and writes"| node_db
node_water_handler -->|"validates points"| node_water_model
node_auth_handler -->|"reads and writes"| node_db
node_auth_handler -->|"issues tokens"| node_auth_middleware
node_auth_handler -->|"uses account types"| node_user_model
node_auth_middleware -->|"checks roles"| node_user_model
node_media_handler -->|"reads and writes"| node_media_db
node_media_handler -->|"validates payloads"| node_comment_model
node_media_handler -->|"serves uploaded files"| node_users
node_db -.->|"runs migrations"| node_migrations
node_user_db -.->|"uses database connection"| node_db

click node_runtime "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/main.go"
click node_health "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/handlers/health.go"
click node_config "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/config/config.go"
click node_water_handler "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/handlers/water.go"
click node_water_model "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/models/water.go"
click node_auth_handler "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/handlers/auth.go"
click node_auth_middleware "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/handlers/auth_middleware.go"
click node_user_model "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/models/user.go"
click node_media_handler "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/handlers/media.go"
click node_comment_model "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/models/comment.go"
click node_db "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/database/sqlite.go"
click node_user_db "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/database/users.go"
click node_media_db "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/database/comments.go"
click node_migrations "https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/database/migrate.go"

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_runtime,node_health,node_config,node_users toneBlue
class node_water_handler,node_water_model toneAmber
class node_auth_handler,node_auth_middleware,node_user_model toneMint
class node_media_handler,node_comment_model toneRose
class node_db,node_user_db,node_media_db,node_migrations toneIndigo
```

## Components

### API runtime

- [HTTP routing](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/main.go): `openwatermap/backend/main.go`
- [Health check](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/handlers/health.go): `openwatermap/backend/handlers/health.go`
- [Runtime config](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/config/config.go): `openwatermap/backend/config/config.go`

### Water reporting

- [Point endpoints](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/handlers/water.go): `openwatermap/backend/handlers/water.go`
- [Water rules](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/models/water.go): `openwatermap/backend/models/water.go`

### Identity and access

- [Account endpoints](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/handlers/auth.go): `openwatermap/backend/handlers/auth.go`
- [JWT and roles](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/handlers/auth_middleware.go): `openwatermap/backend/handlers/auth_middleware.go`
- [User and roles](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/models/user.go): `openwatermap/backend/models/user.go`

### Community media

- [Comments and uploads](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/handlers/media.go): `openwatermap/backend/handlers/media.go`
- [Comment and photo data](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/models/comment.go): `openwatermap/backend/models/comment.go`

### Persistence

- [PostgreSQL access](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/database/sqlite.go): `openwatermap/backend/database/sqlite.go`
- [User records](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/database/users.go): `openwatermap/backend/database/users.go`
- [Comments and photo records](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/database/comments.go): `openwatermap/backend/database/comments.go`
- [Schema migrations](https://github.com/abuba111/openwatermap/blob/main/openwatermap/backend/database/migrate.go): `openwatermap/backend/database/migrate.go`

### Other components

- **Map users**

## Connections

- Map users → HTTP routing: calls API (evidence: `openwatermap/backend/main.go`)
- HTTP routing → Runtime config: loads settings (evidence: `openwatermap/backend/main.go`)
- HTTP routing → PostgreSQL access: opens database (evidence: `openwatermap/backend/main.go`)
- HTTP routing → Point endpoints: routes points (evidence: `openwatermap/backend/main.go`)
- HTTP routing → Account endpoints: routes auth (evidence: `openwatermap/backend/main.go`)
- HTTP routing → Comments and uploads: routes media (evidence: `openwatermap/backend/main.go`)
- HTTP routing → Health check: routes health (evidence: `openwatermap/backend/main.go`)
- HTTP routing → JWT and roles: applies guards (evidence: `openwatermap/backend/main.go`)
- Point endpoints → PostgreSQL access: reads and writes (evidence: `openwatermap/backend/handlers/water.go`)
- Point endpoints → Water rules: validates points (evidence: `openwatermap/backend/handlers/water.go`)
- Account endpoints → PostgreSQL access: reads and writes (evidence: `openwatermap/backend/handlers/auth.go`)
- Account endpoints → JWT and roles: issues tokens (evidence: `openwatermap/backend/handlers/auth.go`)
- Account endpoints → User and roles: uses account types (evidence: `openwatermap/backend/handlers/auth.go`)
- JWT and roles → User and roles: checks roles (evidence: `openwatermap/backend/handlers/auth_middleware.go`)
- Comments and uploads → Comments and photo records: reads and writes (evidence: `openwatermap/backend/handlers/media.go`)
- Comments and uploads → Comment and photo data: validates payloads (evidence: `openwatermap/backend/handlers/media.go`)
- Comments and uploads → Map users: serves uploaded files
- PostgreSQL access → Schema migrations: runs migrations
- User records → PostgreSQL access: uses database connection
