pocket-civilization

Pocket Civilization — passive lifelog civilization simulator

Local privacy controls UI

This repository currently ships a static, local-first privacy controls screen in index.html. It provides visible entry points for:

• exporting local privacy state as JSON;
• deleting local privacy state after confirmation;
• hiding private moments from the local interface;
• excluding the current context from future passive capture;
• placeholder passive capture status before backend/cloud integration exists.

The screen stores preferences in browser localStorage and does not require premium access, cloud sync, or any backend service.

Server

The Go API server lives in server/.

cd server
go test ./...
go run ./cmd/api

Configuration is read from a local .env file and process environment variables, with environment variables taking precedence:

• SERVER_HOST (default: 0.0.0.0)
• SERVER_PORT (default: 8080)

Health endpoints:

• GET /health/live
• GET /health/ready

Database migrations

Initial database migrations live in server/internal/database/migrations/. They define accounts, invites, auth tokens, worlds, world snapshots, movement facts and aggregates, deletion requests, AI jobs, debug traces, and admin audit tables with retention metadata (deleted_at, retained_until, purge_after).

The movement schema stores coarse movement facts and aggregates only; it does not include a raw coordinate stream table.

Verify that migrations apply to an empty database with:

cd server
go test ./internal/database/migrations

Redaction guardrails

Server-side JSON payload guards live in server/internal/redaction. The shared guard is intended for sync, AI, debug, and log ingestion paths and rejects raw GPS arrays, hidden category labels, private anchors, exact geometry, rhythm buckets, and debug/Open Pilot artifact payloads before those values can be stored or logged. Validation errors expose only safe class identifiers and never echo raw payload fragments.

Invite-only auth endpoints:

• POST /auth/invite/claim with invite_token and email sends a fake magic-link mailer message.
• POST /auth/magic/verify with token consumes a magic link and returns access/refresh tokens.
• POST /auth/refresh with refresh_token rotates refresh tokens.
• POST /auth/logout with refresh_token revokes the refresh token.

Privacy API endpoints:

• GET /v1/privacy/export returns account worlds, settlements, and derived AI/debug records. Derived payloads are always redacted.
• DELETE /v1/privacy/settlements/{settlementID} removes the active settlement record and cancels linked AI/debug records.
• DELETE /v1/privacy/worlds/{worldID} removes the active world and its active settlements, then cancels linked AI/debug records.
• DELETE /v1/privacy/account removes all active account worlds/settlements and cancels account AI/debug records.

Delete requests may include backupRetentionDays; returned backup expiry metadata is capped at 30 days.

World snapshot sync endpoints:

• PUT /v1/world/snapshot uploads the account's latest redacted snapshot.
• GET /v1/world/snapshot returns the account's latest snapshot.

Requests are authenticated with X-Account-ID or an opaque Authorization: Bearer ... token. Snapshot uploads use schema version world.snapshot.v1 and optimistic revisions: create with revision: 0, then send the revision returned by the previous response. Stale uploads return 409 with stable error code revision_conflict.

Native iOS app

The native SwiftUI app lives in ios/PocketCivilization/. The Xcode project is generated from project.yml with XcodeGen so project file changes stay reviewable.

cd ios/PocketCivilization
xcodegen generate
xcodebuild test \
  -project PocketCivilization.xcodeproj \
  -scheme PocketCivilization \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro'

The first native milestone is intentionally manual-first: it shows the local civilization dashboard, bootstrap settlement state, privacy controls, and a manual-only passive health state. Passive capture and TestFlight work should only be added after the local MVP, privacy ledger, and deletion/export tests pass.

Phase 5 real-device checklist

Phase 5 passive simulation behavior requires a physical-device/TestFlight pass before release readiness. Use docs/phase-5-real-device-checklist.md to record permission flow, battery/background behavior, dwell/route behavior, private naming, export/delete, and blocker issues.