# CLAUDE.md

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

## Project Overview

CertCenter is a lightweight SSL certificate management platform. It integrates ACME certificate issuance (via certbot), automatic renewal, and multi-server certificate distribution through a Vue 3 WebUI.

## Common Commands

```bash
# Backend
pip install -r requirements.txt          # Install Python deps
python -m backend.main                   # Start server at :8000

# Frontend
cd frontend && npm install && npm run build && cd ..   # Build for production
cd frontend && npm run dev               # Dev server at :5173 (proxies API to :8000)

# Testing
python -m tests.test_setup               # Validate environment
python -m tests.test_e2e --domain X --ak Y --sk Z   # End-to-end cert issuance test

# Start with hash seed fix (Windows)
set PYTHONHASHSEED=0 && python -m backend.main
```

## Architecture

**Backend (FastAPI + SQLAlchemy + SQLite):**
- `backend/main.py` — App entry point, router registration, SPA middleware
- `backend/routers/api.py` — Client-facing API at `/api/*` (Bearer token per-server)
- `backend/routers/admin.py` — Admin API at `/admin/api/*` (HMAC token auth)
- `backend/acme_service.py` — ACME operations via certbot subprocess + AliDNS API
- `backend/models.py` — ORM models: Server, Domain, DeployLog, AcmeConfig, AcmeLog
- `backend/templates_cert/` — Jinja2 templates for deploy scripts (bash/PowerShell)

**Frontend (Vue 3 + Vite + Tailwind CSS):**
- Hash-based routing (`/#/path`) — no server-side routing needed
- `src/App.vue` — Login gate + sidebar layout
- `src/api/index.js` — Axios with auto token injection and 401 handling

**Dual Router Design:**
- `/api/*` — Used by deployment scripts on business servers (token per server)
- `/admin/api/*` — Used by WebUI (single admin user from .env)

**ACME Flow:** certbot is invoked as a subprocess, not used as a library. DNS-01 challenges are handled by calling AliDNS REST API directly. Wildcard certs (`*.example.com`) automatically include the bare domain.

## Key Technical Decisions

- Python 3.11-3.12 required (3.14 lacks pydantic-core wheels)
- SQLite for zero-dependency deployment
- Version-based sync: clients compare integer version numbers, download only on change
- Self-signed cert bootstrap on first HTTPS boot (client scripts use `curl -k`)
- Admin auth: HMAC-based tokens (`username:expiry:signature`), 7-day expiry
- Single admin user configured in `.env` (ADMIN_USERNAME / ADMIN_PASSWORD)