# 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`