Skip to content

CLAUDE.md

Latest commit

 

History

History
70 lines (52 loc) · 2.97 KB

CLAUDE.md

File metadata and controls

70 lines (52 loc) · 2.97 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

TruthStake — an educational news credibility platform where users stake credits on whether news articles are credible, Polymarket-style. Features 3-hour market cycles, blind article evaluation (source hidden until resolution), threaded comments, and source reliability visualizations.

Architecture

Frontend

  • Next.js with SSR and TypeScript (strict mode)
  • Zod for runtime schema validation and type inference — use Zod schemas as the single source of truth for all data shapes (API responses, form inputs, env vars). Derive TypeScript types with z.infer<> rather than writing separate interfaces.
  • TanStack Router for type-safe routing
  • TanStack Form for form state/validation (integrate with Zod resolvers)
  • shadcn/ui + Tailwind CSS for UI components
  • GSAP for staking/payout animations
  • Axios for API calls to backend
  • Google OAuth for authentication

Backend

  • Python FastAPI (async REST API), managed with uv
  • Pydantic (v2, strict mode) for all request/response models and settings — enforce model_config = ConfigDict(strict=True) on all models. Use Annotated types with Field() constraints (e.g., Field(gt=0) for credit amounts). Never pass raw dicts; always validate through Pydantic models.
  • OAuth2 / JWT for auth middleware

Backend Tooling (uv)

All Python commands must use uv. Never use raw pip, python, or venv directly.

# Project setup
uv init backend
cd backend
uv add fastapi pydantic[email] uvicorn sqlalchemy asyncpg

# Run dev server
uv run uvicorn app.main:app --reload

# Add a dependency
uv add <package>

# Add a dev dependency
uv add --dev <package>

# Run any Python script
uv run python <script.py>

# Run tests
uv run pytest

# Run linter/formatter
uv run ruff check .
uv run ruff format .

Databases

  • PostgreSQL — primary transactional database (users, credits, votes, rounds, comments)
  • ClickHouse — analytical database for source visualization dashboards, synced from PostgreSQL

Data Model

Core tables: sources, articles, article_back_sources, users, credit_transactions, rounds, votes, comments, comment_upvotes. Full schema in docs/schema-reference.md.

Key domain concepts:

  • Round: A 3-hour voting window tied to one article. States: open → closed → settled
  • Vote: One per user per round. User stakes credits on credible or not_credible
  • Settlement: Automated — reveals source, determines winner based on sources.is_credible, distributes credits proportionally to winning pool
  • Credit transactions: Immutable ledger (credit_transactions) is the source of truth for balances; users.credits is a denormalized cache

Key Documents

  • docs/PRD.md — full product requirements
  • docs/schema-reference.md — complete database schema with all columns, types, and relationships