Add achievement system architecture proposal for per-game achievements

[Copilot]

Current achievement system is hardcoded with 8 generic cross-game achievements (Specialist/Generalist tiers). No support for per-game tailored achievements or automatic suggestion based on game mechanics.

Proposal Document: ACHIEVEMENT_SYSTEM_PROPOSAL.md

Comprehensive 13-section design for scalable per-game achievement system:

Architecture

• Template library: 15+ reusable patterns (win streaks, high scores, mechanic-specific)
• Suggestion engine: Auto-generates achievements from game metadata (mechanics/categories)
• Hybrid evaluation: SQL queries for aggregations, TypeScript functions for complex logic
• 4 new tables: AchievementTemplate, GameAchievement, PlayerAchievementProgress, AchievementRule

Examples

Concrete achievement sets for different game types:

• Deck-building (Dominion): 6 achievements leveraging hand management mechanics
• Worker placement (Agricola): 6 achievements with efficiency/resource focus
• Cooperative (Pandemic): 6 achievements for team-based progression

Auto-suggestion flow:

// Input: Game with mechanics ["Exploration", "Dice Rolling"]
// Output: Suggested achievements with reasoning
{
  "FIRST_WIN": { threshold: 1, priority: "HIGH" },
  "TOTAL_WINS_N": { threshold: 5, reasoning: "Standard progression" },
  "EXPLORATION_TILES": { threshold: 1, note: "FUTURE - requires event tracking" }
}

Migration

6-phase rollout (12 weeks):

1. Database schema + migrate existing achievements
2. Per-game achievement creation UI
3. Suggestion engine + template application
4. Evaluation engine refactor with caching
5. Notifications, leaderboards, rarity system
6. User-generated content (future)

Decision Points

• Retroactive unlocking strategy for historical sessions
• Score normalization (currently stored as strings)
• Event logging infrastructure for in-game milestone tracking
• Caching strategy (database vs Redis)

No code changes—design proposal only per requirements.

Original prompt

AnyYou are GitHub Copilot acting as a senior software architect.

Task:
Analyze this entire codebase and propose a better “achievement solution” that supports UNIQUE achievements per board game.

Key goals:

• Each board game can have its own tailored achievements (not one-size-fits-all).
• The solution should either:
  (A) include an Achievement Generator approach (data-driven templates + rules), OR
  (B) automatically suggest suitable achievements for a new/unknown game based on game metadata/type/mechanics.
• It must scale as we add more board games and achievements.
• It should be easy to maintain and avoid hardcoding lots of per-game logic scattered across the codebase.

VERY IMPORTANT CONSTRAINTS:

• DO NOT make any code changes.
• DO NOT propose a PR, commit, or “apply edits”.
• Output must be ONLY a suggestion document (like a README.md / ADR / design proposal). If you want to show example interfaces/types, keep them as illustrative snippets inside the document, but do not instruct to implement or modify files yet.

What to do first (analysis steps):

1. Identify where achievements are currently defined, computed, stored, and displayed (search for “achievement”, “badge”, “trophy”, “milestone”, “unlock”, etc.).
2. Summarize the current architecture and pain points (tight coupling, duplication, hardcoded rules, missing metadata, etc.).
3. Identify the board game domain model: how games are represented (IDs, type, tags/mechanics, rules, scoring events, match results, etc.).
4. Identify where “game events” / “match events” / “player actions” exist (the data you could base achievements on).

Deliverable format (single document):
Write a structured proposal titled: “Achievement System Proposal (No Code Changes)”

Include these sections:

• Current State Summary (what exists today)
• Problems / Constraints
• Design Goals (including uniqueness per board game)
• Proposed Architecture (high level)
• Data Model Proposal
  • How achievements are defined (per-game configs, templates, rules)
  • How achievements are evaluated (event-driven, post-game analysis, scheduled jobs, etc.)
  • How achievements are stored and versioned
• Achievement Generation / Suggestion Strategy
  • Inputs (game type, mechanics/tags, player actions/events)
  • How suggestions are produced (template library, heuristic scoring, optional ML later)
  • How to ensure suggestions are “suitable” and not generic
• Examples
  • Example achievement definitions for 2–3 different game styles (e.g. deck-builder, worker placement, co-op)
  • Example of how a new game would get suggested achievements
• Migration Plan (phased rollout, backwards compatibility)
• Risks & Mitigations
• Open Questions / Next Decisions

Output rules:

• Keep it practical and grounded in THIS repo’s structure.
• Use headings, bullet points, and short paragraphs.
• Do not modify any files.
• End with a clear “Recommended Next Step” list (still no code changes).

Now begin by analyzing the repo structure and the existing achievement flow, then write the proposal document.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
gametracker	Error		Jan 14, 2026 10:01pm