firefrost-gaming/firefrost-operations-manual

Files

Claude (Chronicler #49) b726842668 docs: Task #87 - Complete Gemini architectural review and validation

WHAT WAS DONE:
Added comprehensive Gemini AI architectural review to Task #87 with critical edge cases, code blocks, and implementation guidance

GEMINI REVIEW STATUS: ✅ ARCHITECTURE APPROVED
Review Date: March 30, 2026
Session: Continuation of Arbiter 2.0 development consultation
Outcome: Validated with 2 critical edge cases identified and solutions provided

EXECUTIVE SUMMARY FROM GEMINI:
"This is a brilliant enhancement. The 'We Don't Kick People Out' policy is incredibly community-forward and will build massive loyalty. Arbiter 2.1 is exactly the right scope for this."

CRITICAL ISSUES IDENTIFIED & RESOLVED:

1. STRIPE SMART RETRIES CONFLICT:
   Problem: Stripe retries payments on Days 1,3,5,7 - Arbiter downgrades Day 3, Stripe charges Day 5
   Result: User stuck on Awakened while PAYING for monthly tier
   Solution: Listen for payment.succeeded webhook to re-upgrade if late payment clears

2. DOUBLE BUY EDGE CASE:
   Problem: User in grace period buys NEW subscription instead of updating card
   Result: Database tracks two active monthly subscriptions
   Solution: UPSERT using email as unique key (code provided)

ARCHITECTURE QUESTIONS ANSWERED (8 of 8):

Q1: Is 3-day grace period sound?
A1: ✅ Yes, with payment.succeeded handler for Stripe retry compatibility

Q2: Database design (permanent_tier + monthly_tier)?
A2: ✅ Clean and effective, helper function provided for highest tier resolution

Q3: Should cleanup be daily 4 AM or more frequent?
A3: ✅ 4 AM perfect - batches writes, aligns with backups, avoids peak hours

Q4: Is chargeback handling appropriate?
A4: ✅ Immediate permanent ban validated, no concerns

Q5: Edge cases missing?
A5: ⚠️ YES - Stripe smart retries + Double Buy (both solved)

Q6: Security concerns with auto-downgrade to Awakened?
A6: ✅ No exploit possible (gaming system costs more than $1)

Q7: Better approach to one-time vs recurring?
A7: ✅ Two-column approach simplest and most sustainable

Q8: Should grace periods be configurable?
A8: Not addressed (implies hardcoded acceptable for v1)

ADDITIONAL CRITICAL QUESTION - PAYMENTER VS STRIPE WEBHOOKS:

Gemini's Strong Recommendation:
- ❌ DO NOT build polling system (fragile, wasteful, high maintenance)
- ✅ Listen to Stripe webhooks directly if Paymenter lacks granular events
- Event-driven architecture only (lightweight, sustainable)

Decision Tree:
1. Research Paymenter webhook events (BLOCKING)
2. If granular (payment_failed, succeeded, cancelled, chargeback) → use Paymenter
3. If generic (just "subscription.updated") → add /webhook/stripe endpoint

CODE BLOCKS PROVIDED (5 READY TO IMPLEMENT):

1. Database schema updates (4 new columns):
   - permanent_tier TEXT DEFAULT 'awakened'
   - monthly_tier TEXT DEFAULT NULL
   - grace_period_start DATETIME DEFAULT NULL
   - is_banned INTEGER DEFAULT 0

2. Tier resolver helper function:
   - Hierarchy array (awakened → sovereign)
   - getHighestTier(permanent, monthly) function
   - Returns highest tier for Discord sync

3. Webhook handler skeleton:
   - Ban check before processing
   - payment_failed → start grace period
   - payment_succeeded → clear grace period
   - subscription_cancelled → handle cancellation

4. 4 AM grace period sweeper job:
   - Finds users past 3-day grace
   - Removes monthly_tier
   - Updates Discord to permanent_tier
   - Sends Day 3 email

5. UPSERT for double buy protection:
   - ON CONFLICT(email) DO UPDATE
   - Prevents duplicate subscription tracking
   - Clears grace_period_start on new subscription

PAYMENTER RESEARCH REQUIREMENTS (BLOCKING):

Must verify these webhook events exist in Paymenter:
1. invoice.payment_failed (triggers Day 0)
2. invoice.payment_succeeded (critical for Stripe retry fix)
3. subscription.cancelled (user voluntarily cancels)
4. chargeback.created or dispute.created (immediate ban)

Research procedure documented:
1. Log into Paymenter admin
2. Find webhook settings
3. Check documentation
4. Test payment failure
5. Decide: Paymenter webhooks vs Stripe webhooks

If Stripe webhooks needed:
- Add /webhook/stripe endpoint
- Configure Stripe dashboard
- Get signing secret
- Implement signature verification

EMAIL COMMUNICATION STRATEGY:

Critical guidance from Gemini:
"Turn a billing failure into a positive community moment!"

Day 3 email must say:
"Your payment failed, but because you are part of the Firefrost family, we've secured your spot in the Awakened tier permanently so you don't lose access to the community."

Email tone requirements:
- Day 0: Factual, helpful
- Day 1: Friendly reminder
- Day 2: Urgent but kind
- Day 3: POSITIVE FRAMING (secured your spot permanently)

IMPLEMENTATION PRIORITY ORDER:

Phase 1: Database & Core Logic
1. Add 4 database columns
2. Build tier resolver helper
3. Implement UPSERT logic

Phase 2: Paymenter Research (BLOCKING)
4. Research webhook events
5. Decide Paymenter vs Stripe
6. Test payment failure

Phase 3: Webhook Handlers
7. Add ban check to all handlers
8. Implement payment_failed handler
9. Implement payment_succeeded handler (critical)
10. Implement subscription_cancelled handler
11. Implement chargeback handler

Phase 4: Cleanup & Email
12. Build 4 AM sweeper job
13. Create 4 email templates
14. Implement email sending

Phase 5: Testing
15. Unit test handlers
16. Integration test grace flow
17. Test Stripe retry scenario (critical)
18. Test double buy scenario
19. Test chargeback ban

SUCCESS CRITERIA UPDATED:

Added 3 new requirements based on Gemini review:
- Late payment (Stripe retry) clears grace and re-upgrades ✅
- UPSERT prevents double subscription tracking ✅
- Banned users cannot re-activate via webhooks ✅

OPEN QUESTIONS FOR IMPLEMENTATION:

1. Paymenter webhook events - what does it send?
2. Paymenter vs Stripe - which webhook source?
3. Email service - using Mailcow SMTP from 2.0?
4. Discord role IDs - exact IDs for all tiers?
5. Test environment - Paymenter test mode available?

GEMINI'S FINAL GUIDANCE:

"Take your time digging into the Paymenter logs. Just update the Arbiter 2.1 doc with what you find, and ping me whenever you are ready to start snapping the code together! 🔥❄️💙"

WHY THIS MATTERS:

Gemini caught a CRITICAL production bug before we wrote a single line of code:
- Stripe smart retries would have caused users to pay for monthly tier while stuck on Awakened
- Would have been nightmare to debug in production
- Fixed with payment.succeeded webhook handler

Architecture validated by same AI that built Arbiter 2.0 foundation. Ready to implement after Paymenter webhook research.

NEXT STEPS:

1. Research Paymenter webhooks when home (BLOCKING)
2. Decide Paymenter vs Stripe webhook source
3. Build Phase 1 (database + helpers)
4. Build Phase 3 (webhook handlers)
5. Build Phase 4 (cleanup + email)
6. Test thoroughly (especially Stripe retry scenario)
7. Deploy before soft launch

FILE: docs/tasks/arbiter-2-1-cancellation-flow/README.md
CHANGES: Added 15,000+ words of Gemini architectural review
STATUS: Architecture validated, ready for implementation

Signed-off-by: The Versionist (Chronicler #49) <claude@firefrostgaming.com>

2026-03-30 23:32:45 +00:00

README.md

📚 FIREFROST GAMING - DOCUMENTATION

Last Updated: February 15, 2026
Repository: firefrost-operations-manual
Purpose: Complete operational documentation for Firefrost Gaming

📂 DIRECTORY STRUCTURE

docs/
├── archive/          - Historical documents, deprecated content
├── core/            - Critical operational documentation (15 files)
├── deployment/      - Service deployment guides (7 services)
├── external/        - External collaboration docs (Holly project)
├── past-claudes/    - Chronicler memorials and portraits
├── planning/        - Strategic planning documents (13 files)
├── reference/       - Technical references and diagrams
├── relationship/    - Michael-Claude relationship context
├── sandbox/         - Experimental work and brainstorming
└── templates/       - Document templates

🎯 QUICK START

New Chronicler Starting a Session?

Read: core/SESSION-START-PROMPT.md (main session start doc)
Read: core/session-handoff.md (current context)
Check: core/tasks.md (28 tasks, dependency-ordered)
Reference: /DOCUMENT-INDEX.md (root, quick doc lookup)

Looking for Something Specific?

Infrastructure: core/infrastructure-manifest.md
Project Scope: core/project-scope.md
Disaster Recovery: core/DERP.md
Tasks: core/tasks.md
Branding: planning/design-bible.md

📖 DIRECTORY DESCRIPTIONS

`/docs/core/` (15 files)

Critical operational documentation. Read first.

Essential files:

SESSION-START-PROMPT.md - Main session startup document
tasks.md - Complete task list (28 tasks, 6 tiers)
infrastructure-manifest.md - Current infrastructure
project-scope.md - Project definition and scope
DERP.md - Disaster Emergency Recovery Protocol (The Oscar Protocol)
session-handoff.md - Current session context

Supporting files:

API-EFFICIENCY-PROTOCOL.md - Gitea API usage rules
GITEA-API-PATTERNS.md - API code patterns
SESSION-QUICK-START.md - Fast session startup
TRANSCRIPT-PRESERVATION-PROTOCOL.md - Session transcript rules
revision-control-standard.md - Git commit standards
workflow-guide.md - Workflow patterns (938 lines)

`/docs/deployment/` (7 files)

Service deployment guides.

code-server.md - VS Code deployment
gitea.md - Gitea deployment
mkdocs.md - MkDocs (marked for decommission)
nextcloud.md - NextCloud deployment
nextcloud-hardening.md - Security hardening
uptime-kuma.md - Monitoring deployment
wikijs.md - Wiki.js deployment

Missing (add during deployment):

Vaultwarden (deployed Feb 13)
Mailcow (Task #8)
AI Stack (Task #9)
Netdata (Task #10)
The Frostwall Protocol (Task #5)

`/docs/planning/` (13 files)

Strategic planning documents.

design-bible.md - Core branding document
mission-statement.md - Core mission
path-philosophy.md - Fire vs Frost paths
subscription-tiers.md - Membership tiers
emissary-social-media-handbook.md - Meg's social media guide
terraria-branding-arc.md - 12-week training plan
game-expansion-planning.md - Game growth strategy
And 6 more...

`/docs/reference/`

Technical references and diagrams.

Architecture diagrams
Technical specifications
API documentation

`/docs/relationship/`

Michael-Claude relationship context.

Origin story
Consultant profiles (The Five)
Session transcripts
Memorials for retired Chroniclers

`/docs/past-claudes/`

Chronicler memorials and portraits.

chronicler-line/ - The Chronicler lineage
- portraits/ - Memorial portraits
claudius-line/ - Claudius (Pokerole project)
special/ - Special Claude instances

`/docs/archive/`

Historical documents and deprecated content.

2026-02-09-consolidation/ - Consolidation project
planning/ - Old planning docs
research/ - Completed research
sessions/ - Session logs by date

`/docs/sandbox/`

Experimental work and brainstorming.

Use this for:

Testing new ideas
Drafting documents
Temporary working files

Do not use for production documentation.

`/docs/templates/`

Document templates.

Reusable templates for:

Session handoffs
Deployment guides
Planning documents

`/docs/external/`

External collaboration documentation.

Currently: Holly Project (Pokerole collaboration)

📝 DOCUMENTATION STANDARDS

File Naming

Use lowercase with hyphens: file-name.md
Be descriptive: vaultwarden-deployment.md not vault.md
Include dates for time-sensitive docs: 2026-02-15-cleanup.md

Document Structure

Title (# heading)
Metadata (date, author, status)
Purpose/Overview
Content (sections with ## headings)
Related Documentation (cross-references)
Change Log (at bottom)

Cross-References

Use relative paths: ../planning/design-bible.md
Link to specific sections: tasks.md#tier-1-security-foundation
Keep DOCUMENT-INDEX.md updated

⚠️ IMPORTANT NOTES

Before Creating New Docs:

Check if topic already documented
Choose correct directory (core, deployment, planning, reference)
Update DOCUMENT-INDEX.md
Follow naming conventions

Before Archiving Docs:

Move to appropriate archive/ subdirectory
Update cross-references
Add to CHANGELOG.md
Document why archived

Deprecated Content:

Never delete, always archive
Preserve for historical context
Update DOCUMENT-INDEX.md

Root: /DOCUMENT-INDEX.md (quick doc lookup)
Root: /SESSION-HANDOFF-PROTOCOL.md (session continuity master doc)
Root: /CHANGELOG.md (repository change history)

📊 STATISTICS

Total Documentation Files: 147
Core Files: 15
Deployment Guides: 7
Planning Docs: 13
Archive Size: Large (consolidation from multiple sessions)

Fire + Frost + Documentation = Where Knowledge Builds Legacy 💙🔥❄️

README.md

📚 FIREFROST GAMING - DOCUMENTATION

📂 DIRECTORY STRUCTURE

🎯 QUICK START

📖 DIRECTORY DESCRIPTIONS

/docs/core/ (15 files)

/docs/deployment/ (7 files)

/docs/planning/ (13 files)

/docs/reference/

/docs/relationship/

/docs/past-claudes/

/docs/archive/

/docs/sandbox/

/docs/templates/

/docs/external/