Architecture
Octogriffin is a modern full-stack application built on the Next.js framework. It acts as a bridge between GitHub activity and Habitica gamification.
Technology Stack
App Router (Frontend)
Next.js 16 using React Server Components. Styled with Tailwind CSS and Hugeicons.
Serverless Backend
API Routes and Webhook handlers running on Vercel Serverless Functions.
Data Layer
Neon (Serverless PostgreSQL) managed via Prisma ORM for type-safe database access.
Authentication
NextAuth.js handling GitHub OAuth sessions and secure session management.
Event Data Flow
The core of Octogriffin is the transformation of code activity into game stats. Here is the lifecycle of a typical event:
GitHub Event
User pushes code or merges a PR. GitHub sends a POST payload to /api/v1/webhook.
Security Check
The application validates the X-Hub-Signature-256 header against our App Secret to ensure the request is legitimate.
Trigger Matching
The system queries the database for active triggers that match the incoming event (e.g., "Push to Main"). If a match is found, the configured XP/Gold reward is retrieved.
Habitica Sync
Using the user's stored API credentials, Octogriffin sends a score task request to the Habitica API.
Integration Model
GitHub Actor
Octogriffin operates as a GitHub App. It does not use a user's personal access token. Instead, it acts on its own behalf with specific, granular permissions installed on repositories.
Habitica Agent
For Habitica, the app acts as a User Agent. We encrypt and store the user's API User ID and Token to make API calls that simulate the user completing a task.
Asynchronous Processing
after(). This allows us to immediately return a 202 Accepted to GitHub while the trigger matching and API sync happen in the background.