60 lines
1.6 KiB
Markdown
60 lines
1.6 KiB
Markdown
# Storage (JSON-only)
|
||
|
||
## `DSS_HOME` resolution
|
||
|
||
DSS chooses a storage root in this order:
|
||
|
||
1. `$DSS_HOME` if set
|
||
2. `./.dss` if it exists in the current working directory
|
||
3. `~/.dss`
|
||
|
||
This supports:
|
||
- **project-local** storage (recommended when running DSS inside a repo)
|
||
- **shared user** storage (default fallback)
|
||
- **server** storage (explicit `DSS_HOME` volume)
|
||
|
||
## Directory layout
|
||
|
||
Most persistent JSON state lives under:
|
||
|
||
`$DSS_HOME/data/`
|
||
|
||
```
|
||
data/
|
||
_system/
|
||
activity/ # JSONL activity logs (by day)
|
||
cache/ # TTL cache entries (JSON)
|
||
users/ # auth users (JSON-only)
|
||
integration_health.json
|
||
projects/
|
||
<project_id>/
|
||
manifest.json
|
||
components/
|
||
figma/
|
||
integrations.json
|
||
metrics/
|
||
styles/
|
||
tokens/
|
||
teams/
|
||
```
|
||
|
||
## Concurrency / locking
|
||
|
||
The JSON store uses simple file locking (`*.lock`) to reduce corruption when multiple processes write concurrently.
|
||
|
||
## Project-local artifacts
|
||
|
||
In addition to `$DSS_HOME/data/`, DSS also writes project-local artifacts under a repo’s `.dss/` directory, for example:
|
||
|
||
- `.dss/analysis_graph.json` — portable analysis output (commit-friendly).
|
||
- `.dss/config.json` — per-project DSS configuration (used by `ConfigService`).
|
||
- `.dss/runtime-config.json` — runtime/server preferences (when using the headless server wrappers).
|
||
|
||
## What is safe to commit
|
||
|
||
Typical “commit-worthy” artifacts:
|
||
- `<project>/.dss/analysis_graph.json` (generated analysis output)
|
||
|
||
Typical “do not commit” data:
|
||
- per-user caches and secrets under `$DSS_HOME/data/_system/cache`
|