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