Local JSON Storage System
Relevant source files
The following files were used as context for generating this wiki page:
The Local JSON Storage System manages all persistent data for the Freebuff Proxy project. It stores user information, API keys, proxy settings, and account credentials as JSON files within a centralized directory. This system ensures that data survives container restarts and provides a transparent way for administrators to audit or back up the system state.
The system adheres to a "Data in /data" rule, where the /data directory on the container is typically mounted to a local directory on the host. This architecture prevents data loss when the container is deleted or updated.
Sources: CLAUDE.md:73, README_EN.md:104, README.md:103
Data Directory Structure
The system organizes different types of information into specific JSON files and subdirectories. All paths are relative to the /data mount point.
| Data Type | File Path | Description |
|---|---|---|
| Proxy Settings | /data/proxies.json | Stores the global pool of egress proxies. |
| User Management | /data/users.json | Contains users, roles, passwords, and API keys. |
| Account Credentials | /data/credentials/ | Subdirectory containing Freebuff account tokens and login state. |
| Account Ledger | /data/account-state.json | Records the scheduling status (On/Off) of accounts. |
Sources: README_EN.md:104-110, README.md:103-109
File Organization Flow
The following diagram shows how the application interacts with the local storage system to resolve and persist data.
The diagram illustrates the centralized nature of the storage system where the application resolves paths through a config module to access specific JSON assets.
Sources: src/config.ts:15-18, README_EN.md:104
Component Roles and Logic
Configuration and Path Resolution
The src/config.ts module acts as the primary gateway for locating storage assets. It exports helper functions to identify the project root and the specific directory used for account credentials.
projectRootFromModule: Resolves the absolute path of the project.credentialsDir: Specifically points to the location of account credential JSON files.resolveDefaultCredentialsDir: Provides the fallback path for credentials if not explicitly configured.
Sources: src/config.ts:16-17, src/config.ts:31
Integrity and Self-Checking
The system includes automated gates to verify the integrity of the stored JSON files. The documentation check tool ensures that endpoints registered in the code match those described in the API documentation, preventing "drift" between the storage schema and the interface.
- Corrupt File Handling: If a JSON file becomes corrupt, the service typically falls back to default values.
- Dirty Entry Detection: The system identifies invalid records (e.g., missing key fields) during startup, logs the error, and drops the specific entry while keeping the rest of the file intact.
Sources: scripts/gates/checks/doc/check-docs.ts:133-140, README.md:275-280
Operational Persistence
The storage system is designed so that "everything is managed in the web console." When a user changes a proxy setting or adds an account via the browser, the application immediately writes these changes to the corresponding JSON file in the /data directory.
This sequence demonstrates the direct relationship between frontend actions and filesystem persistence.
Sources: README_EN.md:104-110, CLAUDE.md:73
Summary
The Local JSON Storage System provides a lightweight, transparent, and persistent data layer for the Freebuff Proxy. By utilizing standard JSON files and a single /data mount point, it avoids the overhead of a formal database while maintaining strict data separation. The system relies on the src/config module for path resolution and various script gates to maintain data integrity.
Sources: CLAUDE.md:65-73, src/config.ts:8-12