# satrianugrahasaputra/geo-entity-manager architecture

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

- Interactive diagram: https://gitdiagram.com/satrianugrahasaputra/geo-entity-manager
- Repository: https://github.com/satrianugrahasaputra/geo-entity-manager

## Overview

Geo Entity Manager is a web app for viewing and managing geographically located entities. Users browse and filter a map-backed list, inspect details, then add, edit, or delete entities; creation and editing take coordinates from map clicks or a draggable marker. The frontend routes these actions through query hooks and an API client to a Go service, which validates requests and persists entities in PostgreSQL. README documents database migrations and seed data at startup. Backend source excerpts show the API layers; the frontend-to-backend and startup wiring is documented, while unsampled implementation details are omitted.

Main entry points: [`frontend/src/App.tsx`](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/App.tsx) (App state), [`backend/internal/handler/entity_handler.go`](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/handler/entity_handler.go) (Entity handlers), [`frontend/src/components/Sidebar.tsx`](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/components/Sidebar.tsx) (Entity sidebar), [`frontend/src/api/entities.ts`](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/api/entities.ts) (Entity API operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Map management UI"]
  node_app["App state<br/>[App.tsx]"]
  node_sidebar["Entity sidebar<br/>[Sidebar.tsx]"]
  node_form["Entity form<br/>[EntityForm.tsx]"]
  node_map["Interactive map<br/>[Map.tsx]"]
end

subgraph group_webdata["Frontend data access"]
  node_schema["Entity schemas<br/>[entity.ts]"]
  node_entitytypes["Entity types<br/>[entity.ts]"]
  node_hooks["Entity query hooks<br/>[useEntities.ts]"]
  node_operations["Entity API operations<br/>[entities.ts]"]
  node_client["HTTP client<br/>[client.ts]"]
  node_api_types["API types<br/>[api.ts]"]
end

subgraph group_api["Backend API"]
  node_gin["HTTP server<br/>[router.go]"]
  node_handlers["Entity handlers<br/>[entity_handler.go]"]
  node_dto["Request decoding<br/>[decode.go]"]
  node_validation["Request validation<br/>[validator.go]"]
  node_service["Entity service<br/>[entity_service.go]"]
  node_model["Entity model<br/>[entity.go]"]
  node_server["API startup<br/>[main.go]"]
end

subgraph group_persistence["Persistence"]
  node_repository["Entity repository"]
  node_postgres[("PostgreSQL")]
  node_migrations["Schema migrations<br/>[migrate.go]"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_sidebar
node_app -->|"renders"| node_map
node_app -->|"queries entities"| node_hooks
node_sidebar -->|"renders"| node_form
node_form -->|"validates with"| node_schema
node_map -->|"reports location"| node_app
node_sidebar -->|"mutates entities"| node_hooks
node_hooks -->|"calls"| node_operations
node_operations -->|"sends requests"| node_client
node_client -->|"formats errors"| node_api_types
node_operations -->|"uses types"| node_entitytypes
node_entitytypes -->|"infers types"| node_schema
node_client -.->|"HTTP API"| node_gin
node_server -->|"starts"| node_gin
node_gin -->|"routes requests"| node_handlers
node_handlers -->|"decodes requests"| node_dto
node_handlers -->|"validates input"| node_validation
node_handlers -->|"calls"| node_service
node_service -->|"delegates storage"| node_repository
node_repository -->|"reads and writes"| node_postgres
node_repository -->|"maps records"| node_model
node_server -->|"runs migrations"| node_migrations
node_migrations -->|"updates schema"| node_postgres

click node_app "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/App.tsx"
click node_sidebar "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/components/Sidebar.tsx"
click node_form "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/components/EntityForm.tsx"
click node_map "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/components/Map.tsx"
click node_schema "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/schemas/entity.ts"
click node_entitytypes "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/types/entity.ts"
click node_hooks "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/hooks/useEntities.ts"
click node_operations "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/api/entities.ts"
click node_client "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/api/client.ts"
click node_api_types "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/types/api.ts"
click node_gin "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/handler/router.go"
click node_handlers "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/handler/entity_handler.go"
click node_dto "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/handler/decode.go"
click node_validation "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/validation/validator.go"
click node_service "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/service/entity_service.go"
click node_model "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/model/entity.go"
click node_repository "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/repository/entity_repository.go"
click node_migrations "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/repository/migrate.go"
click node_server "https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/cmd/server/main.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_app,node_sidebar,node_form,node_map,node_user toneBlue
class node_schema,node_entitytypes,node_hooks,node_operations,node_client,node_api_types toneAmber
class node_gin,node_handlers,node_dto,node_validation,node_service,node_model,node_server toneMint
class node_repository,node_postgres,node_migrations toneRose
```

## Components

### Map management UI

- [App state](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Entity sidebar](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/components/Sidebar.tsx): `frontend/src/components/Sidebar.tsx`
- [Entity form](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/components/EntityForm.tsx): `frontend/src/components/EntityForm.tsx`
- [Interactive map](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/components/Map.tsx): `frontend/src/components/Map.tsx`

### Frontend data access

- [Entity schemas](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/schemas/entity.ts): `frontend/src/schemas/entity.ts`
- [Entity types](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/types/entity.ts): `frontend/src/types/entity.ts`
- [Entity query hooks](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/hooks/useEntities.ts): `frontend/src/hooks/useEntities.ts`
- [Entity API operations](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/api/entities.ts): `frontend/src/api/entities.ts`
- [HTTP client](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [API types](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/frontend/src/types/api.ts): `frontend/src/types/api.ts`

### Backend API

- [HTTP server](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/handler/router.go): `backend/internal/handler/router.go`
- [Entity handlers](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/handler/entity_handler.go): `backend/internal/handler/entity_handler.go`
- [Request decoding](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/handler/decode.go): `backend/internal/handler/decode.go`
- [Request validation](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/validation/validator.go): `backend/internal/validation/validator.go`
- [Entity service](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/service/entity_service.go): `backend/internal/service/entity_service.go`
- [Entity model](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/model/entity.go): `backend/internal/model/entity.go`
- [API startup](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/cmd/server/main.go): `backend/cmd/server/main.go`

### Persistence

- [Entity repository](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/repository/entity_repository.go): `backend/internal/repository/entity_repository.go`
- **PostgreSQL**
- [Schema migrations](https://github.com/satrianugrahasaputra/geo-entity-manager/blob/main/backend/internal/repository/migrate.go): `backend/internal/repository/migrate.go`

### Other components

- **User**

## Connections

- User → App state: uses (evidence: `README.md`)
- App state → Entity sidebar: renders (evidence: `frontend/src/App.tsx`)
- App state → Interactive map: renders (evidence: `frontend/src/App.tsx`)
- App state → Entity query hooks: queries entities (evidence: `frontend/src/App.tsx`)
- Entity sidebar → Entity form: renders (evidence: `frontend/src/components/Sidebar.tsx`)
- Entity form → Entity schemas: validates with (evidence: `frontend/src/components/EntityForm.tsx`)
- Interactive map → App state: reports location (evidence: `frontend/src/App.tsx`)
- Entity sidebar → Entity query hooks: mutates entities (evidence: `frontend/src/components/Sidebar.tsx`)
- Entity query hooks → Entity API operations: calls (evidence: `frontend/src/hooks/useEntities.ts`)
- Entity API operations → HTTP client: sends requests (evidence: `frontend/src/api/entities.ts`)
- HTTP client → API types: formats errors (evidence: `frontend/src/api/client.ts`)
- Entity API operations → Entity types: uses types (evidence: `frontend/src/api/entities.ts`)
- Entity types → Entity schemas: infers types (evidence: `frontend/src/types/entity.ts`)
- HTTP client → HTTP server: HTTP API (evidence: `README.md`)
- API startup → HTTP server: starts (evidence: `README.md`)
- HTTP server → Entity handlers: routes requests (evidence: `backend/internal/handler/router.go`)
- Entity handlers → Request decoding: decodes requests (evidence: `backend/internal/handler/entity_handler.go`)
- Entity handlers → Request validation: validates input (evidence: `backend/internal/handler/entity_handler.go`)
- Entity handlers → Entity service: calls (evidence: `backend/internal/handler/entity_handler.go`)
- Entity service → Entity repository: delegates storage (evidence: `backend/internal/service/entity_service.go`)
- Entity repository → PostgreSQL: reads and writes (evidence: `backend/internal/repository/entity_repository.go`)
- Entity repository → Entity model: maps records (evidence: `backend/internal/repository/entity_repository.go`)
- API startup → Schema migrations: runs migrations (evidence: `README.md`)
- Schema migrations → PostgreSQL: updates schema (evidence: `README.md`)
