# jfberry/poracleng architecture

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

- Interactive diagram: https://gitdiagram.com/jfberry/poracleng
- Repository: https://github.com/jfberry/poracleng

## Overview

1. **Top-level shape: one Go processor, many responsibilities.**  
   PoracleNG is not split into separate backend services; the `processor/` Go binary owns webhook ingestion, rule matching, template rendering, delivery to chat platforms, bot command handling, reconciliation, and the public HTTP API. The repo root mostly contains configuration, bundled defaults, templates, and operational assets around that core service.

2. **Primary runtime boundaries.**  
   The processor sits between four external systems: Golbat sends Pokémon GO scan webhooks into `POST /`; MySQL stores tracking/state/humans/profiles and lookup data; Discord and Telegram receive outbound alerts and command traffic; and external tools such as PoracleWeb call `/api/*` endpoints for management and reporting.

3. **Webhook intake and event processing pipeline.**  
   Incoming scan data is handled by `processor/internal/webhook` and the HTTP API layer in `processor/internal/api`. The event is normalized, matched against in-memory tracking rules, enriched with game data and translations, then handed off to delivery. Type-specific processors in `processor/cmd/processor/*.go` and `processor/internal/tracker` implement the actual Pokémon, raid, quest, invasion, lure, nest, gym, fort, and maxbattle flows.

4. **State and persistence are centered on MySQL plus in-memory caches.**  
   `processor/internal/db` contains SQL-backed loaders, migration support, diff/cleanup logic, and CRUD/query helpers for trackings, humans, profiles, monsters, raids, quests, lures, invasions, forts, gyms, nests, and maxbattle. The service loads tracking state into memory on startup and reloads it via API calls or scheduled refreshes, so matching is fast and does not depend on per-webhook database queries.

5. **Delivery is a separate subsystem from matching.**  
   `processor/internal/delivery` owns outbound message dispatch, queueing, rate limiting, sanitization, image generation, and platform-specific senders for Discord and Telegram. This boundary matters because the processor can accept high webhook volume, batch or queue outbound messages, and apply platform-specific constraints independently of the detection logic.

6. **Discord/Telegram bots are first-class subsystems, not add-ons.**  
   Discord support is split across `processor/internal/discordbot` and Telegram support across `processor/internal/telegrambot`. These subsystems handle command parsing, thread/channel management, reconciliation, auto-create workflows, keepalive, roles, and webhook/webhook-adjacent interactions. In split-bot Discord mode, one token is used for alerts and another for gateway/commands, which creates a clear operational split between delivery and administration.

7. **The API surface is broad and operationally important.**  
   `processor/internal/api` exposes configuration, reload, tracking CRUD, human/profile management, geofence access, stats, weather, geocoding, master data, test webhook simulation, and message delivery endpoints. This API is the main control plane for external web UIs and admin tooling, so it is part of the system architecture rather than a thin debug interface.

8. **Template rendering and message shaping are explicit layers.**  
   `processor/internal/dts` renders DTS/Handlebars-style templates for Discord/Telegram messages, `processor/internal/rowtext` and `processor/internal/enrichment` assemble human-readable fields, and `processor/internal/i18n` localizes output. The repo’s `config/dts.json`, `partials.json`, `broadcast.json`, and `custom.*.json` files, with bundled `fallbacks/`, are part of this rendering pipeline and define the user-visible message contract.

9. **Geospatial and environmental services are built into the processor.**  
   `processor/internal/geofence`, `processor/internal/geo`, and `processor/internal/geocoding` handle point-in-polygon checks, time zones, sunrise/sunset and map URL generation, and forward geocoding. These are used by matching, area/summary commands, and API endpoints, and they rely on local geofence files plus optional external geocoding providers.

10. **Game-data enrichment is downloaded and cached locally.**  
    `processor/internal/gamedata` and `processor/internal/resources` manage Pokémon, moves, items, types, weather, grunts, and related lookup data. On startup the processor downloads public game datasets into `resources/`, reuses cached copies if needed, and uses them to enrich raw scanner webhooks with names, forms, weaknesses, weather boosts, PvP data, and translation-aware text.

11. **Matching and analytics sit between raw events and outbound output.**  
    `processor/internal/matching`, `processor/internal/validation`, `processor/internal/nlp`, `processor/internal/pvp`, `processor/internal/state`, and `processor/internal/tracker` implement the logic that decides whether a scan event matters, how it maps to user rules, how duplicates are suppressed, how rarity/shiny/summary stats are updated, and how command text is interpreted. This is the main business-logic core of the system.

12. **Operational assets support deployment and observability.**  
    `Dockerfile`, `docker-compose.yml.example`, `ecosystem.config.js`, `start.sh`, and `Makefile` support local, Docker, and pm2-based deployment. Monitoring is exposed via `/metrics` and visualized using the Grafana dashboards under `monitoring/`, with Prometheus scrape examples included.

13. **Tileserver integration is an external rendering boundary.**  
    The `tileserver_templates/` directory contains deployable JSON templates for tileservercache/tileserver integrations used to generate static map imagery for alert embeds and API responses. This is not core matching logic, but it is part of the visual output pipeline and depends on deployment into a separate tileserver environment.

14. **Repository structure reflects runtime concerns.**  
    `examples/` and `fallbacks/` hold editable data files and bundled defaults; `config/` is the operator-controlled overlay; `backups/` and `scripts/` support migration and recovery; `docs/` contains design notes for major subsystems. For an architecture diagram, the most important split is: external inputs → processor core → MySQL/state/enrichment/rendering → Discord/Telegram/API/tileserver outputs.

Main entry points: [`processor/cmd/processor/main.go`](https://github.com/jfberry/poracleng/blob/main/processor/cmd/processor/main.go) (Processor), [`processor/internal/delivery/delivery.go`](https://github.com/jfberry/poracleng/blob/main/processor/internal/delivery/delivery.go) (Delivery), [`processor/internal/matching`](https://github.com/jfberry/poracleng/tree/main/processor/internal/matching) (Matching), [`processor/internal/enrichment`](https://github.com/jfberry/poracleng/tree/main/processor/internal/enrichment) (Enrichment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External systems"]
  node_golbat(("Golbat<br/>webhook source"))
  node_mysql[("MySQL<br/>state store")]
  node_discord(("Discord<br/>delivery target"))
  node_telegram(("Telegram<br/>delivery target"))
  node_poracleweb(("PoracleWeb<br/>admin client"))
end

subgraph group_runtime["Processor runtime"]
  node_processor_bin["Processor<br/>Go binary<br/>[main.go]"]
  node_webhook_api["Ingress<br/>http intake<br/>[receiver.go]"]
  node_api["API layer<br/>control plane<br/>[api.go]"]
  node_matching["Matching<br/>rules engine"]
  node_tracker["Tracker<br/>state logic"]
  node_enrichment["Enrichment<br/>event shaping"]
  node_delivery["Delivery<br/>dispatch layer<br/>[delivery.go]"]
  node_discordbot["Discord bot<br/>bot subsystem<br/>[bot.go]"]
  node_telegrambot["Telegram bot<br/>bot subsystem<br/>[bot.go]"]
  node_db["DB loaders<br/>sql access<br/>[loader.go]"]
  node_state["State cache<br/>in-memory cache<br/>[state.go]"]
  node_gamedata["Game data<br/>lookup cache<br/>[gamedata.go]"]
  node_geoservices["Geo services<br/>spatial utils<br/>[geofence.go]"]
end

subgraph group_assets["Data and templates"]
  node_templates["Templates<br/>render assets<br/>[dts.json]"]
  node_resources["Resources<br/>cached data<br/>[util.json]"]
  node_tileserver_templates["Tileserver templates<br/>map templates<br/>[poracle-raid.json]"]
end

subgraph group_ops["Operations"]
  node_monitoring["Monitoring<br/>dashboards"]
  node_docker_assets["Deploy assets<br/>runtime ops"]
  node_scripts["Scripts<br/>support tools"]
end

node_golbat -->|"scan webhooks"| node_webhook_api
node_poracleweb -->|"admin calls"| node_api
node_webhook_api -->|"normalize + route"| node_matching
node_matching -->|"state updates"| node_tracker
node_tracker -->|"cache refresh"| node_state
node_state -->|"load from sql"| node_db
node_db -->|"persist/query"| node_mysql
node_matching -->|"enrich lookup"| node_gamedata
node_matching -->|"geo context"| node_geoservices
node_webhook_api -->|"shape event"| node_enrichment
node_enrichment -->|"render data"| node_templates
node_enrichment -->|"lookup names"| node_gamedata
node_enrichment -->|"maps/time"| node_geoservices
node_templates -->|"message body"| node_delivery
node_delivery -->|"send alerts"| node_discord
node_delivery -->|"send alerts"| node_telegram
node_discordbot -->|"bot channel"| node_discord
node_telegrambot -->|"bot channel"| node_telegram
node_api -->|"crud + reload"| node_db
node_api -->|"test sends"| node_delivery
node_processor_bin -->|"hosts"| node_webhook_api
node_processor_bin -->|"starts"| node_discordbot
node_processor_bin -->|"starts"| node_telegrambot
node_processor_bin -->|"metrics"| node_monitoring
node_tileserver_templates -.->|"map imagery"| node_delivery
node_resources -->|"cached datasets"| node_gamedata
node_docker_assets -.->|"deploy/run"| node_processor_bin
node_scripts -.->|"migrations/recovery"| node_db

click node_processor_bin "https://github.com/jfberry/poracleng/blob/main/processor/cmd/processor/main.go"
click node_webhook_api "https://github.com/jfberry/poracleng/blob/main/processor/internal/webhook/receiver.go"
click node_api "https://github.com/jfberry/poracleng/blob/main/processor/internal/api/api.go"
click node_matching "https://github.com/jfberry/poracleng/tree/main/processor/internal/matching"
click node_tracker "https://github.com/jfberry/poracleng/tree/main/processor/internal/tracker"
click node_enrichment "https://github.com/jfberry/poracleng/tree/main/processor/internal/enrichment"
click node_delivery "https://github.com/jfberry/poracleng/blob/main/processor/internal/delivery/delivery.go"
click node_discordbot "https://github.com/jfberry/poracleng/blob/main/processor/internal/discordbot/bot.go"
click node_telegrambot "https://github.com/jfberry/poracleng/blob/main/processor/internal/telegrambot/bot.go"
click node_db "https://github.com/jfberry/poracleng/blob/main/processor/internal/db/loader.go"
click node_state "https://github.com/jfberry/poracleng/blob/main/processor/internal/state/state.go"
click node_gamedata "https://github.com/jfberry/poracleng/blob/main/processor/internal/gamedata/gamedata.go"
click node_geoservices "https://github.com/jfberry/poracleng/blob/main/processor/internal/geofence/geofence.go"
click node_templates "https://github.com/jfberry/poracleng/blob/main/examples/dts.json"
click node_resources "https://github.com/jfberry/poracleng/blob/main/resources/data/util.json"
click node_tileserver_templates "https://github.com/jfberry/poracleng/blob/main/tileserver_templates/swifttileserver/poracle-raid.json"
click node_monitoring "https://github.com/jfberry/poracleng/blob/main/monitoring/grafana/poracle-observability-dashboard.json"
click node_docker_assets "https://github.com/jfberry/poracleng/tree/main/Dockerfile"
click node_scripts "https://github.com/jfberry/poracleng/blob/main/scripts/migrate-from-poracle.js"

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_golbat,node_mysql,node_discord,node_telegram,node_poracleweb toneBlue
class node_processor_bin,node_webhook_api,node_api,node_matching,node_tracker,node_enrichment,node_delivery,node_discordbot,node_telegrambot,node_db,node_state,node_gamedata,node_geoservices toneAmber
class node_templates,node_resources,node_tileserver_templates toneMint
class node_monitoring,node_docker_assets,node_scripts toneRose
```

## Components

### External systems

Inbound scanners, state store, chat platforms, and admin tooling

- **Golbat**: webhook source · Sends scan events into the processor
- **MySQL**: state store · Persists tracking, profiles, humans, and lookup data
- **Discord**: delivery target · Receives alerts and bot interactions
- **Telegram**: delivery target · Receives alerts and bot interactions
- **PoracleWeb**: admin client · Calls the public API for management and reporting

### Processor runtime

Single Go binary and its major internal subsystems

- [Processor](https://github.com/jfberry/poracleng/blob/main/processor/cmd/processor/main.go): Go binary · Single runtime that owns ingestion, matching, delivery, bots, and API · `processor/cmd/processor/main.go`
- [Ingress](https://github.com/jfberry/poracleng/blob/main/processor/internal/webhook/receiver.go): http intake · Handles scan intake and control-plane endpoints · `processor/internal/webhook/receiver.go`
- [API layer](https://github.com/jfberry/poracleng/blob/main/processor/internal/api/api.go): control plane · Exposes config, tracking, humans, profiles, tiles, summary, and test endpoints · `processor/internal/api/api.go`
- [Matching](https://github.com/jfberry/poracleng/tree/main/processor/internal/matching): rules engine · Filters and classifies scan events against loaded tracking rules · `processor/internal/matching`
- [Tracker](https://github.com/jfberry/poracleng/tree/main/processor/internal/tracker): state logic · Handles duplicates, rarity, summary buffering, and encounter/state updates · `processor/internal/tracker`
- [Enrichment](https://github.com/jfberry/poracleng/tree/main/processor/internal/enrichment): event shaping · Builds human-readable fields and per-type context · `processor/internal/enrichment`
- [Delivery](https://github.com/jfberry/poracleng/blob/main/processor/internal/delivery/delivery.go): dispatch layer · Queues, rate limits, sanitizes, renders, and sends outbound messages · `processor/internal/delivery/delivery.go`
- [Discord bot](https://github.com/jfberry/poracleng/blob/main/processor/internal/discordbot/bot.go): bot subsystem · Commands, reconciliation, roles, threads, and webhook-adjacent Discord operations · `processor/internal/discordbot/bot.go`
- [Telegram bot](https://github.com/jfberry/poracleng/blob/main/processor/internal/telegrambot/bot.go): bot subsystem · Commands, channel/topic handling, and reconciliation for Telegram · `processor/internal/telegrambot/bot.go`
- [DB loaders](https://github.com/jfberry/poracleng/blob/main/processor/internal/db/loader.go): sql access · Loads and mutates tracking, humans, profiles, monsters, raids, quests, and related state · `processor/internal/db/loader.go`
- [State cache](https://github.com/jfberry/poracleng/blob/main/processor/internal/state/state.go): in-memory cache · Keeps tracking state loaded for fast matching and refresh cycles · `processor/internal/state/state.go`
- [Game data](https://github.com/jfberry/poracleng/blob/main/processor/internal/gamedata/gamedata.go): lookup cache · Downloads and serves Pokémon, moves, weather, grunts, and type data · `processor/internal/gamedata/gamedata.go`
- [Geo services](https://github.com/jfberry/poracleng/blob/main/processor/internal/geofence/geofence.go): spatial utils · Geofences, geocoding, time zones, sun times, and map URLs · `processor/internal/geofence/geofence.go`

### Data and templates

Bundled defaults, cached resources, and rendering assets

- [Templates](https://github.com/jfberry/poracleng/blob/main/examples/dts.json): render assets · DTS templates, partials, broadcasts, and fallback message definitions · `examples/dts.json`
- [Resources](https://github.com/jfberry/poracleng/blob/main/resources/data/util.json): cached data · Locally downloaded lookup data and locale resources · `resources/data/util.json`
- [Tileserver templates](https://github.com/jfberry/poracleng/blob/main/tileserver_templates/swifttileserver/poracle-raid.json): map templates · Deployable tileserver JSON used for static map imagery · `tileserver_templates/swifttileserver/poracle-raid.json`

### Operations

Deployment, observability, and support tooling

- [Monitoring](https://github.com/jfberry/poracleng/blob/main/monitoring/grafana/poracle-observability-dashboard.json): dashboards · Prometheus and Grafana assets for metrics and operations · `monitoring/grafana/poracle-observability-dashboard.json`
- [Deploy assets](https://github.com/jfberry/poracleng/tree/main/Dockerfile): runtime ops · Container, compose, process manager, and startup files · `Dockerfile`
- [Scripts](https://github.com/jfberry/poracleng/blob/main/scripts/migrate-from-poracle.js): support tools · Migration and JSON helper scripts · `scripts/migrate-from-poracle.js`

## Connections

- Golbat → Ingress: scan webhooks · Incoming scan events are posted to the processor
- PoracleWeb → API layer: admin calls · External UI and tooling use the public control plane
- Ingress → Matching: normalize + route · Ingress hands events to matching logic
- Matching → Tracker: state updates · Matching consults and updates tracker state
- Tracker → State cache: cache refresh · Tracker works against loaded in-memory state
- State cache → DB loaders: load from sql · State is hydrated from SQL-backed stores
- DB loaders → MySQL: persist/query · The SQL layer reads and writes MySQL
- Matching → Game data: enrich lookup · Rules use game data for classification and text
- Matching → Geo services: geo context · Geospatial and timezone helpers support matching
- Ingress → Enrichment: shape event · Inbound payloads are enriched before rendering
- Enrichment → Templates: render data · Template inputs are assembled for message output
- Enrichment → Game data: lookup names · Enrichment resolves game-specific metadata
- Enrichment → Geo services: maps/time · Enrichment adds map links and location context
- Templates → Delivery: message body · Rendered content is handed to outbound delivery
- Delivery → Discord: send alerts · Delivery dispatches Discord messages
- Delivery → Telegram: send alerts · Delivery dispatches Telegram messages
- Discord bot → Discord: bot channel · Discord bot manages commands and reconciliation
- Telegram bot → Telegram: bot channel · Telegram bot manages commands and reconciliation
- API layer → DB loaders: crud + reload · API endpoints mutate and reload persisted state
- API layer → Delivery: test sends · API can trigger delivery and test messages
- Processor → Ingress: hosts · Main binary wires HTTP intake and API routes
- Processor → Discord bot: starts · Main binary runs Discord subsystem
- Processor → Telegram bot: starts · Main binary runs Telegram subsystem
- Processor → Monitoring: metrics · Processor exposes operational metrics
- Tileserver templates → Delivery: map imagery · Static map templates support visual alert output
- Resources → Game data: cached datasets · Downloaded lookup data is stored locally
- Deploy assets → Processor: deploy/run · Container and startup assets launch the service
- Scripts → DB loaders: migrations/recovery · Helper scripts support data migration and maintenance
