Skip to content

CLAUDE.md

Latest commit

 

History

History
33 lines (20 loc) · 3.75 KB

CLAUDE.md

File metadata and controls

33 lines (20 loc) · 3.75 KB
Raw

CLAUDE.md

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

Project overview

AgileConfig is a lightweight, distributed configuration center for .NET (comparable to Apollo/Nacos). It supports Docker/IIS deployment, distributed multi-node clustering, multiple environments (DEV/TEST/STAGING/PROD), real-time config push over WebSocket, IConfiguration/IOptions client integration, a RESTful API, version management with rollback, OIDC/SSO, OpenTelemetry, and can also act as a simple service registry. The client SDK lives in a separate repo (git submodule AgileConfig.Client, published on NuGet as AgileConfig.Client) and is not part of this codebase.

Build, test, and run

  • Target framework: net10.0 across all projects.
  • Build: dotnet build AgileConfig.sln
  • Run all tests: dotnet test
  • Run one test project: dotnet test test/AgileConfig.Server.ServiceTests/AgileConfig.Server.ServiceTests.csproj
  • Test framework is MSTest (with Moq for mocking). AgileConfig.Server.ServiceTests uses Testcontainers (MongoDB/MySQL/PostgreSQL) for integration tests, which requires Docker to be running locally.
  • Admin UI frontend (Ant Design Pro / UmiJS, in src/AgileConfig.Server.UI/react-ui-antd): npm install && npm run build; npm test for frontend tests.
  • Run the server directly: dotnet run --project src/AgileConfig.Server.Apisite, or via Docker: docker run -e adminConsole=true -e db__provider=sqlite -e db__conn="Data Source=agile_config.db" -p 5000:5000 kklldog/agile_config:latest.

Architecture

This is a client-server config center. A "node" is one running instance of AgileConfig.Server.Apisite; any node can double as the admin console (adminConsole=true), and nodes cluster together (cluster=true) by auto-discovering and proxying each other (RemoteServerProxyController, ServerNodeController).

Communication: clients talk to a node over WebSocket for real-time config push (src/AgileConfig.Server.Apisite/Websocket/ — WebsocketHandlerMiddleware.cs, WebsocketCollection.cs, MessageHandlers/), with message contracts defined in the shared Agile.Config.Protocol project. Config fetch/management also goes over REST (Controllers/api/ for the client-facing API; top-level Controllers/ for admin/management endpoints).

Layering (dependency direction): Apisite → IService/Service → Data.Abstraction → Data.Repository.{Freesql|Mongodb} (chosen by Data.Repository.Selector) → Data.{Freesql|Mongodb} → Data.Entity. Event/EventHandler projects provide in-process domain events for decoupling side effects from the main service logic.

Storage backends: selected at runtime via the db:provider setting, resolved through Data.Repository.Selector. Relational backends (sqlserver, mysql, sqlite, npgsql, oracle) go through FreeSql; mongodb goes through the MongoDB driver directly. There is no Redis dependency. Per-environment DB overrides are supported via db:env:{TEST|STAGING|PROD} config keys.

Admin UI: a separate React + Ant Design Pro (UmiJS) app under src/AgileConfig.Server.UI/react-ui-antd, served by the Apisite host through UIExtension/ReactUIMiddleware.cs. It is not an MSBuild project and is not part of AgileConfig.sln — build/test it independently with npm.

Key runtime config (src/AgileConfig.Server.Apisite/appsettings.json): urls, adminConsole, cluster, saPassword, defaultApp, pathBase, preview_mode, db:provider/db:conn, JwtSetting:*, SSO:OIDC:*, otlp:*. Logging is configured via nlog.config.

Note: src/AgileConfig.Server.SyncPlugin* directories exist on disk but contain only stale build output and are not referenced by the solution — treat them as dead code, not an active plugin system.