How jfberry/poracleng works
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: main.go Processor · delivery.go Delivery · matching Matching · enrichment Enrichment
Components 24
External systems
Inbound scanners, state store, chat platforms, and admin tooling
- Golbat · Sends scan events into the processor
- MySQL · Persists tracking, profiles, humans, and lookup data
- Discord · Receives alerts and bot interactions
- Telegram · Receives alerts and bot interactions
- PoracleWeb · Calls the public API for management and reporting
Processor runtime
Single Go binary and its major internal subsystems
- Processor · Single runtime that owns ingestion, matching, delivery, bots, and API
processor/cmd/processor/main.go - Ingress · Handles scan intake and control-plane endpoints
processor/internal/webhook/receiver.go - API layer · Exposes config, tracking, humans, profiles, tiles, summary, and test endpoints
processor/internal/api/api.go - Matching · Filters and classifies scan events against loaded tracking rules
processor/internal/matching - Tracker · Handles duplicates, rarity, summary buffering, and encounter/state updates
processor/internal/tracker - Enrichment · Builds human-readable fields and per-type context
processor/internal/enrichment - Delivery · Queues, rate limits, sanitizes, renders, and sends outbound messages
processor/internal/delivery/delivery.go - Discord bot · Commands, reconciliation, roles, threads, and webhook-adjacent Discord operations
processor/internal/discordbot/bot.go - Telegram bot · Commands, channel/topic handling, and reconciliation for Telegram
processor/internal/telegrambot/bot.go - DB loaders · Loads and mutates tracking, humans, profiles, monsters, raids, quests, and related state
processor/internal/db/loader.go - State cache · Keeps tracking state loaded for fast matching and refresh cycles
processor/internal/state/state.go - Game data · Downloads and serves Pokémon, moves, weather, grunts, and type data
processor/internal/gamedata/gamedata.go - Geo services · 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 · DTS templates, partials, broadcasts, and fallback message definitions
examples/dts.json - Resources · Locally downloaded lookup data and locale resources
resources/data/util.json - Tileserver templates · Deployable tileserver JSON used for static map imagery
tileserver_templates/swifttileserver/poracle-raid.json
Operations
Deployment, observability, and support tooling
- Monitoring · Prometheus and Grafana assets for metrics and operations
monitoring/grafana/poracle-observability-dashboard.json - Deploy assets · Container, compose, process manager, and startup files
Dockerfile - Scripts · Migration and JSON helper scripts
scripts/migrate-from-poracle.js
Connections 28
- 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