Eagle Eye — Architecture and Operations

Eagle Eye is an internal competitor price-monitoring tool for Account Managers (AMs). It scrapes competitor URLs (Social Media, Eatigo, Chope, bank offers, loyalty programmes), normalises those offers against HungryHub packages, and surfaces a daily dashboard so AMs can track and act on price-parity discrepancies.

Repo: hungryhub-team/eagle-eye
Default branch: main
Pairs with: hunger-games (Apify + Facebook scraper that feeds raw competitor data)

Architecture

Account Manager (browser)
        │
        ▼
  client/  (React + Vite + TanStack Router)
        │
        ▼
  server/  (Hono + Bun + Prisma + Better Auth)   ──► PostgreSQL
        │                                          ──► Redis
        ▼
  worker/  (BullMQ + Bun)  ─── background jobs
        │
        ▼
  go-service/  (Go + Fiber + Clean Architecture)
        │
        ├── PostgreSQL
        ├── Redis
        ├── MongoDB
        └── Hunger Games API  (competitor data feed)

Services

`_app_services/frontend-app/` — Turborepo monorepo (v0.5.1)

Package	Purpose	Key tech
`client/`	User-facing web app	React, Vite, TanStack Router, shadcn/ui, Tailwind CSS
`server/`	Backend-for-frontend	Hono, Bun, Prisma, Better Auth, BullMQ, PostgreSQL
`worker/`	Background job processor	BullMQ, Redis, Bun
`shared/`	Shared types and validation	TypeScript, Zod

`_app_services/go-service/` — Core backend API

Built with Go + Fiber following Clean Architecture (handler → usecase → repository layers).

Entrypoint	Purpose
`cmd/api`	Main REST API server (JWT/RSA auth, Swagger docs)
`cmd/asynq_worker`	Background job processor (Asynq)
`cmd/scheduler`	Cron scheduler

Key integrations: PostgreSQL (GORM), Redis, MongoDB, Facebook Graph API, Apify, Open Router (AI), golang-migrate.

Repository structure

_app_services/
  frontend-app/        Turborepo monorepo
    client/            React frontend
    server/            BFF server
    worker/            BullMQ worker
    shared/            Zod schemas + TS types
  go-service/          Core Go backend
    cmd/               api / asynq_worker / scheduler entrypoints
    internal/          handler / usecase / repository / middleware
    config/            DB, Redis, Logger config
    entity/            Domain entities and DTOs
    deploy/            Docker + deployment configs
api-client-docs/       Bruno API collection (Eagle Eye API)
architecture/          Excalidraw system diagrams
deploy/                Deployment scripts
docs/                  Developer documentation

Common development tasks

Regenerate Swagger docs (Go service)

cd _app_services/go-service
swag init -g cmd/api/main.go

Regenerate mocks (Go service)

cd _app_services/go-service
mockery --all

Run database migrations (Go service)

# Up
migrate -path internal/migrations -database "$DATABASE_URL" up

# Down (one step)
migrate -path internal/migrations -database "$DATABASE_URL" down 1

Run the full stack locally

# From frontend-app/ (Turborepo)
bun install
bun run dev        # starts client + server + worker concurrently

# Go service separately
cd _app_services/go-service
go run cmd/api/main.go

Browse API docs (Go service)

Swagger UI is served at /swagger/index.html when the Go service is running locally.

Analytics — PostHog

Eagle Eye uses PostHog Cloud (US region, project ID 455524) for product analytics and session recording.

Automatic: pageviews and session recordings are captured for all authenticated users.

Custom events:

Event	Trigger
`user_authenticated`	Successful login (Google or email)
`restaurant_data_synced`	AM clicks Sync Data and job completes
`restaurant_monitoring_toggled`	AM turns monitoring on/off for a restaurant
`restaurant_searched`	AM submits a search or filter on the restaurants page
`restaurant_link_edited`	AM saves changes in the restaurant edit sheet
`change_feed_action_marked`	AM marks a change feed item with a resolution
`promo_comparison_viewed`	AM opens a promo comparison modal
`promo_feedback_submitted`	AM submits a data quality report on a promo
`ai_process_retry_triggered`	AM retries AI processing on a promo
`market_intelligence_filtered`	User changes month/year on the Market Intelligence page
`task_created`	User creates a task

Implementation: src/lib/posthog.ts in the client. Disabled when VITE_POSTHOG_KEY is unset (safe for local dev).

Secret: VITE_POSTHOG_KEY GitHub Actions repository secret — baked into the Docker image at build time as a Vite env var.

Hunger Games: competitor data scraper that feeds Eagle Eye — hungryhub-team/hunger-games
API collection: api-client-docs/Eagle Eye API/ (Bruno)
Architecture diagrams: architecture/overview.excalidraw, architecture/services.excalidraw

Keyboard shortcuts

HungryHub Knowledge Base