enterprise-saa-s-dashboard-design/CLAUDE.md

CLAUDE.md

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

Project Overview

This is a Chinese-language enterprise SaaS device management platform (地空业务支撑平台——生产管理子系统) built with Next.js App Router. It manages the full lifecycle of geophysical instruments (device registration, BOM configuration, license/authorization management, repair orders, firmware, and scrap records).

Tech Stack

• Frontend: Next.js 16, React 19, TypeScript 6, Tailwind CSS 4
• Database: SQLite via better-sqlite3 (file-based, located at data/app.db)
• Icons: lucide-react
• Forms: react-hook-form + zod
• Secondary backend: FastAPI in python_backend/ for device activation and encrypted license generation

Common Commands

# Install dependencies
npm install

# Start Next.js dev server (http://localhost:3000)
npm run dev

# Build for production
npm run build

# Start production server
npm run start

# Run linting
npm run lint

Python Backend

The FastAPI service in python_backend/ handles device check-in, encrypted license generation, and activation reporting independently from the Next.js app.

cd python_backend
pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Architecture

Database Layer (src/lib/db.ts)

• Uses better-sqlite3 with WAL mode and foreign keys enabled.
• getDb() returns a singleton Database instance. The DB file is created at data/app.db relative to process.cwd().
• initTables() defines the full schema on first run (tables: devices, device_models, materials, bom_templates, config_files, licenses, repair_orders, scrap_records, firmware, applications, app_platform_versions, etc.).
• migrateDatabase() handles incremental schema changes (e.g., adding config_id, license_file, device_sn to the licenses table, creating license_download_logs and license_templates).
• generateLicenseFile() builds a SHA256-signed JSON license payload.

Data Fetching

• Frontend: Uses a lightweight custom hook useApi(url, defaultValue) defined in src/lib/hooks.ts (standard fetch + useState/useEffect). No React Query usage in practice despite being in package.json.
• Backend API: Implemented as Next.js Route Handlers under src/app/api/. Each endpoint typically calls seedIfEmpty() (currently a no-op that just ensures the DB is open) and then uses getDb() to run SQL queries.
• API routes generally support GET (list), POST (create), PUT (update), and DELETE.

Page Structure (App Router)

• src/app/layout.tsx provides the root layout with a sidebar navigation and header.
• src/app/components/sidebar.tsx defines the navigation groups: 设备 (Devices), 物料 (Materials), 软件 (Software), 维修 (Repair).
• Major routes:
  • / — Dashboard with statistics overview
  • /devices — Device list with batch filtering and pagination
  • /devices/[sn] — Device detail / BOM view
  • /registration — Register new device
  • /models — Device model management
  • /models/bom — BOM template management
  • /materials/* — Material (board/component) inventory and categories
  • /app-versions — Mobile app release management
  • /repair — Repair work orders
  • /scrap — Scrap/disposal records
  • /licenses — License/authorization configuration and JSON file generation
  • /config-files — Device technical parameter configs
  • /firmware — Firmware version management

Styling

• Tailwind CSS v4 is imported in src/styles/index.css (@import 'tailwindcss').
• Additional custom styles in src/styles/theme.css and src/styles/fonts.css.
• Many components also use inline style props for specific colors (primary brand color is #4a7c59).

Path Aliases

• @/* maps to ./src/* in tsconfig.json.

Key Development Notes

• No test suite is configured. There are no test runners or test files in the repo.
• No pre-commit hooks or CI configuration were found.
• Database schema changes: When modifying the schema, update initTables() for new tables and migrateDatabase() for alterations to existing tables, since the app uses a single SQLite file that persists across restarts.
• License file generation: The licenses API automatically generates a signed JSON license on POST/PUT by calling generateLicenseFile() from src/lib/db.ts.
• Python backend is separate: The Next.js app does not depend on the FastAPI backend for normal operation. The Python service is specifically for field-device activation flows and encrypted license distribution to mobile apps.