docs(logging): document structured logs workspace

- add roadmap note for the new CCS logging surface

- record logging architecture and codebase ownership

- add logging standards for bounded, redacted runtime logs

Refs #926
This commit is contained in:
Tam Nhu Tran committed 2026-04-08 15:57:14 -04:00
1 parent 87c781a6a2
commit 548edda58b
4 files changed
+29 -3

No files matched your search

+10 -1
View File
@@ -1,6 +1,6 @@
# CCS System Architecture
Last Updated: 2026-03-28
Last Updated: 2026-04-07
High-level architecture overview for the CCS (Claude Code Switch) system.
@@ -18,6 +18,7 @@ The system consists of two main components:
Dashboard localization (i18n) architecture and contributor workflow are documented in [Dashboard i18n Guide](../i18n-dashboard.md).
CCS v7.34 adds Image Analysis Hook for vision model proxying through CLIProxy with automatic injection for all profile types.
CCS v7.67 adds a native structured logging lane for CCS-owned runtime events, backed by `src/services/logging/`, bounded JSONL files under `~/.ccs/logs/`, and a dedicated dashboard `/logs` route.
```
+===========================================================================+
@@ -216,6 +217,14 @@ For detailed provider flows (CLIProxyAPI, legacy GLMT compatibility, quota manag
## Configuration Architecture
### CCS Logging Architecture
- Shared logging contract lives in `src/services/logging/` and is used for CCS-owned runtime diagnostics, request tracing, and bounded recent-entry reads.
- Config lives at top-level `logging.*` in `~/.ccs/config.yaml`; `cliproxy.logging.*` still controls upstream CLIProxy runtime files only.
- CCS-owned runtime logs write to `~/.ccs/logs/current.jsonl` and rotate into `~/.ccs/logs/archive/` based on policy.
- Dashboard exposure uses native `/api/logs/config`, `/api/logs/sources`, and `/api/logs/entries` endpoints plus the `System -> Logs` React page.
- Request logging explicitly skips `/api/logs` reads so the log viewer does not recursively log itself.
### Config File Hierarchy
```