# K-Photos

Self-hosted media orchestrator and gallery. Alternative to Apple Photos, Google Photos, and Immich.

## Philosophy

- **Files are sacred** — original file bytes and embedded metadata are never modified. Ever.
- **No lock-in** — all metadata exportable to standard formats (XMP, JSON). Stop using K-Photos and your tagged, organized file system remains intact.
- **Virtual layer** — all edits (dates, tags, albums, face regions) live in a separate layer. DB at runtime, sidecar exports for portability. Corrupt the layer? Rebuild from originals.
- **Modular** — core works without AI/ML. Face detection, classification, smart search are optional plugins.
- **BYOS** — bring your own storage. Local NAS, S3, GCS — the domain doesn't care.

## Architecture

Hexagonal / DDD with CQRS. Dependencies point inward:

```
Infrastructure (Axum, Postgres, NATS, S3)
  -> Adapters (Controllers, Repos, Storage Providers)
    -> Application (Commands / Queries)
      -> Domain (Entities, Value Objects, Ports, Services)
```

### Bounded Contexts

| Context | Purpose |
|---|---|
| **Identity** | Users, roles, RBAC permissions, groups, refresh tokens |
| **Storage** | Volumes, library paths, ingestion, quotas, BYOS |
| **Catalog** | Assets, metadata layers, stacks, derivatives, duplicates, visibility filtering |
| **Organization** | Albums, tags, collections (smart albums) |
| **Sharing** | Share scopes, targets, links, invite codes, visibility filters |
| **Sidecar** | XMP/JSON export, sync state, conflict resolution |
| **Processing** | Jobs, batches, plugins, pipelines, directory scanner |

### Project Structure

```
crates/
  domain/               pure Rust — entities, value objects, ports, services
    common/             errors, events, value objects (SystemId, Checksum, Email,
                        Username, MimeType, RelativePath, etc.)
    identity/           user, role, permission, group, refresh token
    storage/            volumes, library paths, ingestion, quotas
    catalog/            assets, metadata, stacks, derivatives, duplicates
    organization/       albums, tags, collections
    sharing/            share scopes, targets, links, invites
    sidecar/            sidecar records, sync config
    processing/         jobs, batches, plugins, pipelines

  application/          CQRS commands + queries with Arc<dyn Port> injection
    identity/commands/  RegisterUser, LoginUser, RefreshToken, Logout
    identity/queries/   GetProfile
    storage/commands/   RegisterVolume, RegisterLibraryPath, IngestAsset
    storage/queries/    CheckQuota
    catalog/commands/   RegisterAsset, UpdateMetadata, CreateStack, DeleteStack,
                        DeleteAsset, DetectLivePhotos, ResolveDuplicate
    catalog/queries/    GetTimeline, GetAsset, GetStack, ReadAssetFile,
                        ReadDerivative, SearchAssets
    organization/       CreateAlbum, ManageAlbumEntries, TagAsset, GetAlbum
    sharing/            ShareResource, GenerateShareLink, RevokeShare, AccessSharedResource
    sidecar/            ExportSidecar, DetectChanges, Import, ResolveConflict, FullExport/Import
    processing/         EnqueueJob, StartJob, CompleteJob, FailJob, ExecutePipeline,
                        ManagePlugin, ConfigurePipeline, ListJobs, BatchProgress
    testing/            in-memory repo fakes + stub ports (in_memory_repo! macro)

  api-types/            HTTP request/response DTOs with OpenAPI derives
  adapters/
    auth/               bcrypt password hashing, JWT token issuer (configurable expiry)
    postgres/           all repository implementations, event store, migrations
    storage/            local filesystem + S3 (feature-gated)
    exif/               EXIF metadata extraction
    thumbnail/          derivative generation
    sidecar/            XMP sidecar reader/writer
    event-payload/      domain event serialization
    event-transport/    composite publisher (NATS + event store)
    nats/               NATS JetStream transport
  presentation/         axum handlers, routes, extractors, middleware, parsers
  bootstrap/            config, DI wiring, entry point
  worker/               background job runner (NATS consumer)
```

### Auth

- JWT access tokens (1h expiry, configurable)
- Refresh token rotation (30d, SHA-256 hashed, stored in Postgres)
- `POST /auth/login` — returns access + refresh tokens
- `POST /auth/refresh` — rotates refresh token, issues new pair
- `POST /auth/logout` — revokes all refresh tokens for user
- `require_auth` middleware on all protected routes (defense in depth)
- Handlers still use `JwtClaims` extractor for user_id — middleware is the safety net
- Admin-only endpoints gated by role check (processing, storage, sidecar management)

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `DATABASE_URL` | yes | — | Postgres connection string |
| `JWT_SECRET` | yes | — | HMAC secret for JWT signing |
| `NATS_URL` | no | `nats://localhost:4222` | NATS server URL |
| `STORAGE_PATH` | no | `./data/media` | Local file storage root |
| `HOST` | no | `0.0.0.0` | Bind address |
| `PORT` | no | `8000` | Bind port |
| `CORS_ALLOWED_ORIGINS` | no | — | Comma-separated origins |
| `RUST_LOG` | no | `info` | Log level filter |

## Development

```bash
# run tests (no DB required)
cargo test --workspace

# format + lint
cargo fmt --all
cargo clippy --workspace
```

206 tests cover domain entities, services, application use cases, and visibility filtering.

## Docker

```bash
docker build -t k-photos .
docker run -e DATABASE_URL=... -e JWT_SECRET=... -e NATS_URL=... -p 8000:8000 k-photos
```

Worker (background jobs):
```bash
docker run -e DATABASE_URL=... -e NATS_URL=... k-photos ./k_photos-worker
```

## License

[MIT](LICENSE)