Skip to content

Latest commit

 

History

History
225 lines (175 loc) · 7.83 KB

CLAUDE.md

File metadata and controls

225 lines (175 loc) · 7.83 KB

Points: GenLayer Testnet Program Tracking System

📚 Quick Reference Documentation

Important: This project has detailed documentation for faster development:

  • Backend Documentation: See backend/CLAUDE.md for Django structure, API endpoints, models, and patterns
  • Frontend Documentation: See frontend/CLAUDE.md for Svelte 5 structure, routes, components, and API integration
  • Session Management: See SESSIONS.md for the Git worktree-based development session system

⚠️ Keep documentation updated: When making changes to the codebase, update the relevant CLAUDE.md file to help future development sessions.

Development Sessions & Worktrees

This project uses a custom session management system with Git worktrees. See SESSIONS.md for complete documentation on:

  • Creating and managing parallel development sessions
  • Port allocation and tmux window management
  • Claude Code session persistence across worktrees
  • Troubleshooting common issues

Quick commands:

./session-mgmt add <name>     # Create new session
./session-mgmt list            # Show all sessions
./session-mgmt resume [name]   # Resume after restart
./session-mgmt remove <name>   # Remove session

Svelte 5 Important Notes

Runes Mode and Props

The frontend uses Svelte 5 with runes mode enabled. This means:

  • DO NOT use export let for props - This will cause an error
  • ALWAYS use $props() instead for component props
// ❌ WRONG - This will cause an error in runes mode
export let params = {};

// ✅ CORRECT - Use $props() in Svelte 5
let { params = {} } = $props();

Git Workflow & Guidelines

Branch Strategy

Important: The dev branch is the main merging branch for all development work.

  • Always create pull requests targeting dev, not main
  • The main branch is reserved for production releases
  • Feature branches should be based on and merged into dev

No Attribution in Commits

When creating git commits, DO NOT include Claude attribution lines such as:

Keep commit messages clean and focused on the changes made.

Important Terminology

Never Use "Badge" - Always Use "Contribution"

IMPORTANT: The word "badge" should NEVER be used in the UI or code comments. Always use "contribution" instead:

  • ❌ WRONG: "Claim your badge", "Badge earned", "Badge requirements"
  • ✅ CORRECT: "Complete your journey", "Contribution earned", "Journey requirements"
  • ❌ WRONG: "Builder Badge", "Validator Badge"
  • ✅ CORRECT: "Builder Welcome Contribution", "Validator Waitlist Contribution"

The system tracks contributions, not badges. Each journey completion results in a contribution being recorded.

Environment Setup

Frontend Development

When working with the frontend, always activate the Node.js environment before using npm commands:

# Activate the environment before using npm
cd [..]/points/frontend
source ../backend/env/bin/activate
# Then run npm commands
npm install
npm run dev
npm test

Backend Development

For backend development, activate the Python virtual environment:

# Activate the Python virtual environment
cd [..]/points/backend
source env/bin/activate
# Then run Python/Django commands
python manage.py runserver

Project Overview

Points is a points and contribution tracking system specifically designed for the GenLayer Foundation's Testnet Program. It serves as a comprehensive platform that tracks, rewards, and visualizes community contributions to the GenLayer ecosystem. Each participant action earns badges and points, with the system applying dynamic multipliers to transform action points into global points that determine rankings on the leaderboard.

The system represents an experiment in creating autonomous and trustless GLF (GenLayer Foundation) programs that will eventually become part of the Deepthought DAO.

Technical Architecture

Backend (Python/Django)

The backend is built with Django and Django REST Framework, providing a robust API for tracking and managing contributions. The architecture consists of several key components:

  1. Main Django Apps:

    • users: Custom user management system with email-based authentication
    • contributions: Tracking different types of contributions and their associated points
    • leaderboard: Global ranking system with dynamic multipliers
    • utils: Shared utilities and base models
    • api: Core API functionality

  2. Database Models:

    • User: Extended Django user model with additional fields for blockchain address
    • ContributionType: Different categories of contributions (Node Running, Uptime, Blog Posts, etc.)
    • Contribution: Individual contribution records linking users to contribution types
    • ContributionTypeMultiplier: Dynamic multipliers for different contribution types
    • LeaderboardEntry: User rankings based on total points

  3. Key Features:

    • JWT-based authentication
    • CORS support for frontend integration
    • Automatic point calculation with multipliers
    • Dynamic rank calculations

Frontend (Svelte 5)

The frontend is planned to be built with Svelte 5, though development appears to be in early stages with only the package.json file created. The frontend will provide:

  1. User Interface:

    • Dashboard for viewing personal contributions
    • Global leaderboard
    • Contribution submission and verification
    • Badge collection display

  2. Integration:

    • API integration with the Django backend
    • JWT authentication
    • Real-time updates

Data Flow

  1. Contribution Recording:

    • Users make contributions to the GenLayer ecosystem
    • Contributions are recorded with evidence (URLs, etc.)
    • Each contribution is assigned points based on its type

  2. Point Calculation:

    • Base points are assigned to each contribution
    • Dynamic multipliers transform base points into global points
    • Multipliers can change over time, but previously calculated points remain frozen

  3. Leaderboard Updates:

    • User's total points are calculated from all contributions
    • Rankings are determined by total points
    • Ties receive the same rank

Development Status

The project appears to be in its early stages of development. The backend structure is set up with Django apps and models defined, but many planned features are not yet implemented according to the ROADMAP.md. The frontend is just beginning development with only a package.json file created.

Current Progress:

  • Backend structure established
  • Key models defined
  • Authentication system set up
  • API framework in place

Next Steps (from ROADMAP.md):

  • Complete database schema implementation
  • Implement basic API endpoints
  • Create Svelte 5 frontend skeleton
  • Implement user authentication integration
  • Develop badge and points system functionality

Integration with GenLayer Ecosystem

Tally is designed to integrate with the broader GenLayer ecosystem, particularly the Testnet Program. It will serve as the official tracking system for:

  1. Validator Contributions:

    • Node uptime
    • Network participation

  2. Developer Contributions:

    • Code contributions
    • Bug reports
    • Documentation

  3. Community Contributions:

    • Blog posts
    • Social media engagement
    • Community support

Long-term plans include integration with the Deepthought DAO and potential on-chain recognition of contributions.

Future Considerations

According to the roadmap, future plans include:

  1. Integration with the Deepthought DAO
  2. On-chain recognition of contributions
  3. Automated contribution verification
  4. Mobile application development

The system is designed to be a stepping stone towards more autonomous and trustless governance mechanisms within the GenLayer ecosystem.