pocket-civilization

Pocket Civilization — private movement-fact civilization simulator

Alpha direction

Pocket Civilization is an invite-only Passive AI Digest Alpha: a private mobile prototype that turns user-approved, derived movement facts into a fictional civilization diary. It does not upload raw tracks, sensitive payloads, public social data, billing data, or unrestricted location histories.

Primary source of truth:

• CONTEXT.md — product contract and scope gates
• docs/adr/0001-passive-ai-digest-alpha.md — approved north-star decision
• docs/roadmap.md — epic sequencing
• docs/epics/final-check.md — acceptance/evidence matrix

Current repo state

This repository currently contains the backend and iOS prototype skeletons plus the alpha planning, privacy, architecture, release, and implementation contracts. No production iOS or backend runtime is present yet. ||||||| 6cfe334 Pocket Civilization — passive lifelog civilization simulator 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.