# CLAUDE.md

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

## Project Overview

Gitflux is a Nuxt-based web application that provides a better Git UI experience. It's built on top of Nuxt UI framework with GitHub API integration using Octokit for accessing repositories and organizations.

## Development Commands

- **Start development server**: `pnpm dev` (runs on http://localhost:3000)
- **Build for production**: `pnpm build`
- **Preview production build**: `pnpm preview`
- **Lint code**: `pnpm lint` (uses oxlint)
- **Format code**: `pnpm format` (uses oxfmt)
- **Type checking**: `pnpm typecheck`
- **Install dependencies**: `pnpm install`

## Architecture

### Core Stack
- **Framework**: Nuxt 4.3+ with TypeScript
- **UI Framework**: Nuxt UI 4.4+ (built on Tailwind CSS 4.1+)
- **GitHub Integration**: Octokit 5.0+ for GitHub API calls
- **Validation**: Valibot for form and data validation
- **Icons**: Lucide and Simple Icons via Iconify
- **Package Manager**: pnpm 10.28+

### Application Structure
- `app/` - Main application code following Nuxt conventions
- `app/pages/` - File-based routing with dynamic routes for GitHub orgs and repos
- `app/components/` - Vue components including Form.vue and AppLogo.vue
- `app/composables/` - Composables for GitHub API integration
- `vendor/npmx/` - Third-party vendor code (npmx components and functionality)

### Key Components & Composables

#### GitHub Integration (`app/composables/useGithub.ts`)
- `useAuthenticatedUser(token)` - Authenticates and returns GitHub username
- `useGithubOrg(org)` - Fetches organization data with caching
- `useGithubRepo(owner, repo)` - Fetches repository data with caching
- Uses Nuxt's `useAsyncData` for automatic caching and SSR compatibility
- Token management through cookies (`github_token`)

#### Routing Structure
- `/` - Landing page with user authentication display
- `/[org]` - Organization overview page
- `/[org]/[repo]` - Repository details page

### Configuration Files
- `nuxt.config.ts` - Nuxt configuration with UI module and routing rules
- `app.config.ts` - UI theme configuration (green primary, slate neutral)
- `.oxlintrc.json` / `.oxfmtrc.json` - Code quality tool configurations
- `tsconfig.json` - TypeScript configuration using Nuxt's reference setup

## Development Guidelines

### Reference Implementation
Use `vendor/npmx/` as a reference implementation for:
- Nuxt-specific layout patterns and component organization
- Frontend design concepts and UI patterns
- Component architecture and composition techniques
- Best practices for Nuxt UI framework usage

### GitHub API Usage
- Authentication tokens should be stored in cookies as `github_token`
- All GitHub API calls go through the `useGithub.ts` composables
- Use the provided caching patterns with `useAsyncData` for performance
- Handle loading, error, and success states in components

### UI and Styling
- Follow Nuxt UI component patterns and conventions
- Use the configured color scheme (green primary, slate neutral)
- Leverage Tailwind CSS classes and Nuxt UI's design system
- Maintain responsive design principles

#### Typography
- **Body text**: Mona Sans (`font-sans`) - A strong and versatile typeface designed with Degarism, inspired by industrial-era grotesques
- **Headings**: Hubot Sans (`font-heading`) - Mona Sans's robotic sidekick with geometric accents for technical feel
- **Code/Monospace**: Monaspace Krypton (`font-mono`) - For code blocks, inline code, and technical content

### Code Quality
- Run `pnpm lint` and `pnpm typecheck` before committing
- Use Valibot for form validation schemas
- Follow TypeScript strict mode practices
- Maintain clean component composition with proper setup scripts

### Component Architecture
- Use `<script setup lang="ts">` for all Vue components
- Import types explicitly when needed
- Utilize Nuxt's auto-imports for composables and utilities
- Keep components focused and maintain clear separation of concerns

## CI/CD Pipeline
The project uses GitHub Actions with the following checks:
- Code linting with oxlint
- TypeScript type checking
- Node.js 22 on Ubuntu latest
- pnpm package management