CLAUDE.md — Grit Framework Project Context

This file exists to help Claude Code (and other AI agents) maintain context across sessions. Read this FIRST before doing any work.

What is This Project?

Grit is a full-stack meta-framework that combines:

Go backend (Gin web framework + GORM ORM)
Next.js frontend (React + App Router + TypeScript)
Admin panel (Filament-like resource-based admin dashboard)
All in a monorepo with shared types and validation

Tagline: Go + React. Built with Grit.

Creator: MUKE-coder (GitHub: github.com/MUKE-coder)

Predecessor: This project evolved from GORM Studio (github.com/MUKE-coder/gorm-studio), a visual database browser for GORM that is now embedded within Grit.

Key Documents — READ THESE

Document	Location	Purpose
GRIT.md	`/GRIT.md`	Master specification — what Grit is, features, architecture, folder structure, tech stack, monetization. THE SOURCE OF TRUTH.
PHASES.md	`/PHASES.md`	Development phases with checkboxes. Build one phase at a time. Never skip ahead.
This file	`/CLAUDE.md`	Quick context for AI agents. You're reading it.

Before writing ANY code, read GRIT.md and PHASES.md to understand what you're building.

Current State

Current Phase: Phase 5 — Polish & Launch Status: In Progress Last Updated: 2026-03-03 (Grit UI 91-component expansion)

What's Been Built

What's In Progress / Phase 5

Tech Stack (Do Not Deviate)

Layer	Technology	Notes
Backend	Go 1.21+	Use `go mod` for dependencies
Web framework	Gin	Not Echo, not Fiber, not Chi
ORM	GORM	Not sqlx, not sqlc, not ent
Database	PostgreSQL (prod), SQLite (quick start/testing)
Frontend	Next.js 14+ with App Router	NOT Pages Router
Styling	Tailwind CSS + shadcn/ui	NOT Material UI, NOT Chakra
Data fetching	React Query (TanStack Query)	NOT SWR, NOT Apollo
Validation	Zod	Shared between frontend and generated from Go types
Monorepo	Turborepo + pnpm	NOT npm, NOT yarn
Cache/Queue	Redis	Using `asynq` for job queues
File storage	S3-compatible (AWS S3, Cloudflare R2, MinIO)
Email	Resend
Containerization	Docker + Docker Compose
DB browser	GORM Studio	Our own tool, embedded in the API

Architecture Rules

Folder Structure

The folder structure is defined in GRIT.md. Follow it exactly. Here's the abbreviated version:

project-root/
├── grit.config.ts
├── docker-compose.yml
├── packages/shared/          # Zod schemas, TS types, constants
├── apps/
│   ├── api/                  # Go backend (Gin + GORM)
│   │   ├── cmd/server/       # Entry point
│   │   └── internal/         # All Go code (models, handlers, services, middleware, etc.)
│   ├── web/                  # Next.js main frontend
│   └── admin/                # Next.js admin panel
└── grit/                     # CLI tool (Go)

Naming Conventions

Thing	Convention	Example
Go files	snake_case	`user_handler.go`
Go structs	PascalCase	`type User struct`
Go functions	PascalCase (exported), camelCase (unexported)	`GetUsers`, `parseToken`
TypeScript files	kebab-case	`use-users.ts`, `api-client.ts`
React components	PascalCase files	`DataTable.tsx`, `StatsCard.tsx`
API routes	plural, lowercase	`/api/users`, `/api/posts`
Database tables	plural, snake_case	`users`, `blog_posts`
Zod schemas	PascalCase + Schema	`UserSchema`, `CreatePostSchema`
CSS classes	Tailwind utilities	No custom CSS unless absolutely necessary

Code Style

Go:

Always handle errors explicitly. Never ignore errors with _.
Use fmt.Errorf("context: %w", err) for error wrapping.
Keep handlers thin — business logic goes in services.
Use struct tags: gorm:"...", json:"...", binding:"...".
Group imports: stdlib, external, internal.

TypeScript/React:

Use functional components only. No class components.
Use React hooks. State with useState, effects with useEffect.
All data fetching through React Query hooks. No fetch in components.
Validate all API inputs with Zod.
Export types explicitly. Use interface for objects, type for unions.

Both:

Meaningful variable names. No single letters except in loops.
Comments for WHY, not WHAT.
Keep functions small (<50 lines preferred).

Design System

Theme (Dark Mode Default):

--bg-primary:    #0a0a0f
--bg-secondary:  #111118
--bg-tertiary:   #1a1a24
--bg-elevated:   #22222e
--bg-hover:      #2a2a38
--border:        #2a2a3a
--text-primary:  #e8e8f0
--text-secondary:#9090a8
--text-muted:    #606078
--accent:        #6c5ce7  (purple)
--accent-hover:  #7c6cf7
--success:       #00b894
--danger:        #ff6b6b
--warning:       #fdcb6e
--info:          #74b9ff

Fonts:

UI: Onest (weights: 400, 500, 600, 700)
Code: JetBrains Mono (weights: 400, 500, 600)

Design Feel: Premium CRM / dark mode SaaS tool. Not generic Bootstrap. Not Material Design. Think Linear, Vercel Dashboard, or Raycast — dark, polished, fast.

API Response Format

All API endpoints must follow this format:

Success (single item):

{
  "data": { ... },
  "message": "User created successfully"
}

Success (list with pagination):

{
  "data": [ ... ],
  "meta": {
    "total": 100,
    "page": 1,
    "page_size": 20,
    "pages": 5
  }
}

Error:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": {
      "email": "This field is required"
    }
  }
}

HTTP status codes: 200 (OK), 201 (Created), 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 422 (Validation Error), 500 (Server Error).

Git Commit Convention

Use conventional commits:

feat: add user authentication handlers
fix: resolve JWT token refresh race condition
docs: update API reference for user endpoints
refactor: extract pagination logic to shared service
test: add integration tests for auth flow
chore: update Go dependencies
style: format code with gofmt

Common Pitfalls — Avoid These

Don't use Pages Router in Next.js. We use App Router exclusively.
Don't install dependencies not in the tech stack without explicit approval.
Don't create custom CSS files. Use Tailwind utilities and shadcn/ui.
Don't put business logic in handlers. Handlers call services, services contain logic.
Don't hardcode values. Use .env variables and config structs.
Don't skip error handling in Go. Every error must be handled.
Don't use any type in TypeScript. Define proper types.
Don't deviate from the folder structure. It's the foundation of the framework's conventions.
Don't build features from a later phase. Follow PHASES.md sequentially.
Don't compromise on the dark theme aesthetic. Every UI must look premium.

Quick Reference Commands

# Development
grit dev                          # Start all services
grit generate resource <n>     # Generate full-stack resource
grit migrate                      # Run DB migrations
grit sync                         # Sync Go types → TypeScript
grit studio                       # Open GORM Studio

# Docker
docker compose up -d              # Start infrastructure (DB, Redis, MinIO)
docker compose down               # Stop everything

# Go API
cd apps/api && go run cmd/server/main.go   # Run API directly
cd apps/api && air                          # Run with hot reload

# Frontend
cd apps/web && pnpm dev           # Run Next.js web app
cd apps/admin && pnpm dev         # Run admin panel

# Monorepo
pnpm install                      # Install all dependencies
turbo build                       # Build all apps
turbo dev                         # Dev mode for all apps

Session Checklist for AI Agents

When starting a new session:

✅ Read this file (CLAUDE.md)
✅ Read GRIT.md for full specification
✅ Read PHASES.md to know the current phase
✅ Check the "Current State" section above for progress
✅ Look at existing code to understand what's been built
✅ Continue from where the last session left off
✅ Update the "Current State" section when you complete tasks
✅ Commit work with conventional commit messages

Last context update: 2026-03-03 — Phase 5 nearly complete. All technical items done: Grit UI Registry, Go API tests, frontend test scaffolding (Vitest+RTL+Playwright), 30-day social content (SOCIAL.md). Only remaining: public launch execution. All Go tests passing (generate + scaffold packages).

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CLAUDE.md — Grit Framework Project Context

What is This Project?

Key Documents — READ THESE

Current State

What's Been Built

What's In Progress / Phase 5

Tech Stack (Do Not Deviate)

Architecture Rules

Folder Structure

Naming Conventions

Code Style

Design System

API Response Format

Success (single item):

Success (list with pagination):

Error:

Git Commit Convention

Common Pitfalls — Avoid These

Quick Reference Commands

Session Checklist for AI Agents

FilesExpand file tree

CLAUDE.md

Latest commit

History

CLAUDE.md

File metadata and controls

CLAUDE.md — Grit Framework Project Context

What is This Project?

Key Documents — READ THESE

Current State

What's Been Built

What's In Progress / Phase 5

Tech Stack (Do Not Deviate)

Architecture Rules

Folder Structure

Naming Conventions

Code Style

Design System

API Response Format

Success (single item):

Success (list with pagination):

Error:

Git Commit Convention

Common Pitfalls — Avoid These

Quick Reference Commands

Session Checklist for AI Agents