Skip to content

CLAUDE.md

Latest commit

 

History

History
72 lines (48 loc) · 4.74 KB

CLAUDE.md

File metadata and controls

72 lines (48 loc) · 4.74 KB

CLAUDE.md

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

Essential Commands

  • make reviewable-api / make reviewable-ui — lint:fix + type:check (run before PRs)
  • cd backend && npm run migration:new — create new DB migration
  • cd backend && npm run generate:schema — regenerate Zod types from DB after migration changes

Both backend and frontend use @app/* as path alias to ./src/*.

Repository Structure

Infisical is an open-source secret management platform. Monorepo layout:

infisical/
├── backend/               # Fastify 4 API server (see backend/CLAUDE.md)
├── frontend/              # React 18 SPA (see frontend/CLAUDE.md)
├── docs/                  # Documentation site (Mintlify-based)
├── docker-compose.dev.yml        # Local dev (PostgreSQL, Redis, backend, frontend, Nginx)
├── docker-compose.prod.yml       # Production deployment stack
├── docker-compose.bdd.yml        # BDD testing environment
├── docker-compose.e2e-dbs.yml    # E2E test databases (Oracle, SAP, Snowflake, etc.)
├── Dockerfile.standalone-infisical       # Standalone image (frontend + backend)
├── Dockerfile.fips.standalone-infisical  # FIPS-compliant standalone image
├── .github/               # CI workflows, PR template
└── CLAUDE.md               # This file
  • backend/ — Fastify 4 API server, TypeScript, PostgreSQL via Knex, BullMQ queues. See backend/CLAUDE.md for architecture, patterns, and commands.
  • frontend/ — React 18 SPA, Vite 6, TanStack Router + React Query, Tailwind CSS v4. See frontend/CLAUDE.md for architecture, patterns, and commands.
  • docs/ — Product documentation site. Has its own Dockerfile for building. Reference docs for up-to-date feature descriptions and API usage.

Enterprise features live in backend/src/ee/ (services and routes), registered before community routes so they can override/extend them.

Self-Hosted Deployment

Infisical supports self-hosted deployment via Docker. Key considerations:

  • Dockerfile.standalone-infisical — single-container image with both frontend and backend; used for simple deployments.
  • Dockerfile.fips.standalone-infisical — FIPS 140-2 compliant variant for regulated environments. Be strict about not introducing dependencies that break FIPS compliance.
  • docker-compose.prod.yml — production compose with backend, PostgreSQL, and Redis.
  • New backend dependencies should be evaluated carefully — they affect container size, FIPS compliance, and the encryption boundary. Check docs/ for self-hosted deployment documentation when in doubt.

Dependency Policy

Both backend/ and frontend/ enforce a minimum release age of 7 days for npm packages (configured via .npmrc in each directory). This means npm install will only resolve package versions published at least 7 days ago, as a supply-chain security measure.

Cross-Cutting Patterns

Auth & Permissions

Auth modes (JWT, IDENTITY_ACCESS_TOKEN, SCIM_TOKEN, MCP_JWT) are extracted in backend/src/server/plugins/auth/. Authorization uses CASL (@casl/ability) with project-level and org-level permission checks — see backend/CLAUDE.md for backend details and frontend/CLAUDE.md for frontend permission hooks/HOCs. Note: API_KEY and SERVICE_TOKEN auth modes are deprecated — do not use them in new code.

Service Factory + Manual DI (Backend)

No IoC container. Every service is a factory function with explicit dependencies. The entire dependency graph is wired in backend/src/server/routes/index.ts — see backend/CLAUDE.md for the full wiring map and patterns.

API Layer (Frontend)

React Query + Axios with query key factories per domain. Each API domain in frontend/src/hooks/api/ has queries.tsx, mutations.tsx, and types.tsx — see frontend/CLAUDE.md for conventions.

Keeping CLAUDE.md Up to Date

When making significant changes to the codebase (new services, architectural shifts, new patterns, major refactors), update the relevant CLAUDE.md file(s) with high-level findings. This includes this root file for cross-cutting concerns, backend/CLAUDE.md for backend changes, and frontend/CLAUDE.md for frontend changes. The goal is to keep these files accurate as living documentation so future sessions start with correct context.

Wiring a New Full-Stack Feature

  1. Backend: Create service module, migration, wire DI, add routes — see checklist in backend/CLAUDE.md
  2. Frontend: Add API hooks in src/hooks/api/<domain>/, create page/view, wire route — see frontend/CLAUDE.md for routing and component patterns
  3. Run make reviewable-api and make reviewable-ui before submitting