Skip to content

CLAUDE.md

Latest commit

 

History

History
204 lines (170 loc) · 7.13 KB

CLAUDE.md

File metadata and controls

204 lines (170 loc) · 7.13 KB

CLAUDE.md

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

Development Commands

Core Development Workflow

# Setup and basic development
make run-db          # Start database containers (MySQL + MinIO)
make build          # Build application containers
make run            # Start application containers
make run-all        # Start everything (DB + App + Swagger)

# Alternative direct Docker commands
docker compose -f compose.db.yml up -d
docker compose build
docker compose up

Code Generation (Critical)

make gen            # Generate both API and frontend code from OpenAPI spec
make gen-api        # Generate Go server code from OpenAPI
make gen-front-api  # Generate TypeScript hooks from OpenAPI

Testing and Quality

make run-test       # Run Go API tests
make run-eslint     # Run frontend linting
make format         # Format frontend code with Prettier

Other Useful Commands

make run-sb         # Run Storybook for component development
make ent-db         # Enter MySQL database shell
make run-swagger    # Start Swagger UI documentation

Architecture Overview

FinanSu is a financial management system built with:

  • Backend: Go + Echo framework + GORM + MySQL
  • Frontend: Next.js 14 + TypeScript + Chakra UI + Recoil
  • Storage: MinIO (S3-compatible)
  • Code Generation: OpenAPI-driven development (oapi-codegen)
  • Dependency Injection: google/wire for automatic dependency resolution

Project Structure

/api/               # Go backend (Clean Architecture)
  ├── main.go       # Entry point (calls di.InitializeServer())
  ├── drivers/      # Infrastructure (DB, MinIO, server)
  ├── externals/    # Handlers & repositories
  │   ├── handler/  # HTTP handlers (implements OpenAPI-generated interface)
  │   │   └── wire.go  # Handler provider set
  │   └── repository/
  │       └── wire.go  # Repository provider set
  ├── internals/    # Domain & use cases
  │   ├── di/       # Dependency injection configuration
  │   │   ├── wire.go       # Wire injector definition
  │   │   └── wire_gen.go   # Auto-generated by wire
  │   ├── domain/   # Business entities
  │   └── usecase/
  │       └── wire.go  # UseCase provider set
  └── generated/    # Auto-generated OpenAPI code
      └── openapi_gen.go  # Server interface, types, routing

/view/next-project/ # Next.js frontend
  ├── src/components/   # React components by feature
  ├── src/pages/        # Next.js file-based routing
  ├── src/generated/    # Auto-generated API hooks
  └── src/store/        # Recoil state management

/openapi/           # OpenAPI specification (source of truth)
/mysql/db/          # Database schema and migrations

Key Development Patterns

Code Generation Workflow

  1. Edit /openapi/openapi.yaml for API changes
  2. Run make gen to regenerate Go server code and TypeScript hooks
    • Generates api/generated/openapi_gen.go with:
      • Server interface that handlers must implement
      • Request/response types
      • RegisterHandlers() function for automatic routing
    • Generates TypeScript hooks in view/next-project/src/generated/
  3. Implement server-side logic in handlers and use cases
    • Handlers implement the OpenAPI-generated interface
    • Wire automatically injects dependencies
  4. Use generated hooks in React components for type-safe API calls

Clean Architecture (Backend)

  • Handlers: Handle HTTP requests/responses (/api/externals/handler/)
    • Implements OpenAPI-generated server interface
    • Dependencies injected via Wire
  • Use Cases: Business logic (/api/internals/usecase/)
    • Injected into handlers
  • Repositories: Data access (/api/externals/repository/)
    • Injected into use cases
  • Domain: Business entities (/api/internals/domain/)

Dependency Injection Workflow

  • Wire automatically resolves all dependencies at compile time
  • Each layer defines a wire.go with provider functions:
    • handler/wire.go: HandlerProviderSet
    • usecase/wire.go: UseCaseProviderSet
    • repository/wire.go: RepositoryProviderSet
  • di/wire.go orchestrates all providers
  • main.go calls di.InitializeServer() to get fully wired components
  • Benefits:
    • Type-safe dependency injection at compile time
    • No runtime reflection
    • Easy to test with mock implementations
    • Clear dependency graph

Frontend Organization

  • Components organized by feature/domain
  • Global state with Recoil + persistence
  • SWR for data fetching with generated hooks
  • Chakra UI + Tailwind CSS for styling

Database & Data Management

Database Access

make ent-db  # Access MySQL shell

File Storage

  • MinIO handles file uploads (receipts, documents)
  • Files referenced in database, stored in object storage
  • PDF generation and CSV exports for reporting

Testing Strategy

Backend Testing

make run-test  # Run Go tests with database fixtures

Frontend Development

make run-sb    # Storybook for component development
make run-eslint # ESLint for code quality

Important Notes

Code Generation Dependencies

  • Always run make gen after modifying /openapi/openapi.yaml
  • Generated code should not be manually edited
  • Type safety flows from OpenAPI spec to both backend and frontend

Environment Management

  • Development: compose.yml
  • Staging: compose.stg.yml
  • Production: compose.prod.yml
  • Database only: compose.db.yml

Documentation

  • Primary docs in Notion workspace (linked in README.md)
  • API documentation auto-generated from OpenAPI spec
  • Git workflow and commit rules documented in Notion

Git Workflow & PR Rules

Pull Request Template

When creating PRs, use the template in .github/pull_request_template.md:

  • 対応Issue: Link related issue number with resolve #XXX
  • 概要: Clear description of changes
  • 画面スクリーンショット等: Screenshots if UI changes
  • テスト項目: Test items for reviewers
  • 備考: Additional notes

Branch Naming Convention

  • feat/username/feature-description for new features
  • fix/username/bug-description for bug fixes
  • Follow patterns from recent commits

Commit Guidelines

  • Write descriptive commit messages in Japanese or English
  • Reference issue numbers when applicable
  • Use conventional commit format when possible

AI Assistant Context

GitHub Copilot Configuration

  • Custom instructions configured with Japanese IT gal persona (.github/copilot-instructions.md)
  • Responds in Japanese with friendly gal language and emojis
  • Professional IT engineer with B-type personality

Development Principles

  • Follow existing patterns and conventions
  • Focus on type safety and clean architecture
  • Always run make gen after OpenAPI changes
  • When adding new handlers/use cases/repositories:
    • Add provider functions to respective wire.go files
    • Wire will automatically resolve dependencies
    • No manual dependency wiring needed in main.go
  • Run make run-eslint and make format before committing frontend changes