GameGrip API v0.8.1

AI-powered gaming incident intelligence. Players report bugs → the system fingerprints, clusters, crawls the web for fixes, and publishes blog posts with solutions — all automatically.

Architecture

Player Report → API (ingest + fast classify <2ms)
                  ↓
            Fingerprint (algorithmic: category, severity, hash)
                  ↓
            Prioritiser (score 0-1.0, decide pipeline action)
                  ↓
            Worker Pipeline:
              → Crawl (web search for fixes)
              → Enrich (cluster intelligence + confidence evolution)
              → Evidence (provenance tracking + contradiction detection)
              → Blog (certainty-adapted language)
                  ↓
            System Intelligence (cross-game patterns, hotspots, surges)

3-Tier AI

Tier	Role	Speed	Implementation
Tier 1	Fast Classifier	<2ms	Pure algorithmic — categories, severity, fingerprint hash
Tier 2	Enrichment AI	~5s	Crawl synthesis, cluster intel inheritance, confidence evolution
Tier 3	System Intelligence	~15s	Cross-game patterns, hotspots, category surges. Runs every 6h

3-Layer Memory

Layer	Scope	Storage
Issue	Individual reports	fingerprints, evidence, confidence_log, issue_timeline
Cluster	Groups of similar issues	clusters, cluster_fingerprints
System	Platform-wide trends	system_memory

Issue Lifecycle

new → rising → trending → critical → stabilised → resolved
                                                      ↓
                                                  regressed

Certainty Levels

suspected → probable → confirmed (or unresolved on contradiction)

Quick Start

# Install
npm install

# Set up environment
cp .env.example .env
# Edit .env with your database credentials

# Run MySQL schema
mysql -u root < backend/schema.sql

# Start API server
npm start

# Start worker (separate terminal)
npm run worker

Deploy (PM2)

pm2 start backend/server.js --name gamegrip-api
pm2 start backend/worker.js --name gamegrip-worker
pm2 save && pm2 startup

Scheduled Tasks (built into worker)

Schedule	Task
10:00 UK daily	Crawl batch (all fingerprinted issues)
11:00 UK daily	Blog generation (all enriched issues)
Wed 06:00 UK	Deep crawl (rising/trending/critical, priority ≥ 0.7)
Every 6h	System intelligence cycle

API Endpoints

Public (Zone 1)

Method	Endpoint	Description
GET	/	Service info
GET	/health	Health check
GET	/api/blog	Published blog posts
POST	/api/contact	Contact form

Authenticated (Zone 2 — JWT required)

Method	Endpoint	Description
POST	/api/issues	Submit an issue report
GET	/api/issues/:id	Get issue details
GET	/api/issues?status=...	Filter issues by pipeline status
PATCH	/api/blog/:id/publish	Publish a blog draft (admin)

Intelligence (Zone 2)

Method	Endpoint	Description
GET	/api/intelligence/fingerprints	All fingerprints
GET	/api/intelligence/clusters	All clusters
GET	/api/intelligence/clusters/:id	Cluster detail + linked issues
GET	/api/intelligence/timeline/:issueId	Issue state timeline
GET	/api/intelligence/confidence/:issueId	Confidence history
GET	/api/intelligence/evidence/:issueId	Evidence chain
GET	/api/intelligence/priorities	Priority-ranked issues
GET	/api/intelligence/stats	Dashboard stats
GET	/api/intelligence/system	System memory entries
GET	/api/intelligence/system/hotspots	Detected hotspots
GET	/api/intelligence/system/cross-game	Cross-game patterns

Internal Only (Zone 3 — localhost)

Method	Endpoint	Description
POST	/api/crawl/ingest	Crawl result ingest
POST	/api/intelligence/system/run	Trigger system intelligence cycle

Project Structure

backend/
├── server.js              # Express API server (Zone 1/2/3 routing)
├── worker.js              # Pipeline worker (fingerprint → crawl → enrich → blog)
├── db.js                  # MySQL connection pool
├── ai.js                  # Tier 1 classifier + Tier 2 enrichment AI
├── fingerprint.js         # Algorithmic fingerprinting (categories, severity, hashing)
├── intelligence.js        # Cluster management, confidence evolution, evidence
├── prioritiser.js         # Priority scoring algorithm
├── system-intelligence.js # Tier 3: cross-game, hotspots, surges, time decay
├── blog.js                # Certainty-adapted blog generation
├── blog-runner.js         # Standalone blog batch runner
├── crawler.js             # Web search + fix extraction
├── bridge.js              # Jaffa AI ↔ Grip Protocol bridge
├── schema.sql             # Full MySQL schema
├── middleware/
│   ├── auth.js            # JWT verification + role checking
│   ├── internal-only.js   # Localhost-only middleware
│   └── rate-limits.js     # Tiered rate limiting
└── routes/
    ├── issues.js          # Issue CRUD
    ├── blog.js            # Blog endpoints
    ├── contact.js         # Contact form
    ├── crawl-ingest.js    # Internal crawl results
    ├── intelligence.js    # Intelligence dashboard API
    └── mobile-crawl.js    # Mobile crawl endpoint

frontend/                  # Minimal API frontend
├── index.html
├── app.js
└── style.css

Security

• 3 trust zones: public, authenticated (JWT), internal (localhost only)
• JWT roles: user, developer, admin, studio, system
• CORS: whitelist only — no wildcards
• Rate limiting: tiered per route (AI: 5/min, crawl: 2/hr, reads: 30/min)
• Helmet: full HTTP security headers

Tech Stack

• Node.js 18+ / Express 4
• MySQL 8.0+ (InnoDB, utf8mb4)
• PM2 process manager
• node-cron scheduling

License

MIT — see LICENSE

Architecture