An Entryway for multiple unchanged Bluesky reference PDS instances. It moves ePDS email OTP authentication into the PDS's supported Entryway boundary and provides account management, authorization and identity operations.
This repository is self-contained. Application source, sandbox orchestration, architecture and acceptance documentation live here; no sibling Entryway checkout is required. External repositories and Lexidraw designs are references, not runtime or documentation dependencies.
Status: one application organized by vertical features, with ports/adapters
limited to browser authentication, mail sending and database. Preserved MJS is
owned by its feature. The database boundary uses Drizzle ORM
1.0.0-rc.4 with fresh schemas and asynchronous operations: SQLite or PostgreSQL
on one node, PostgreSQL on multiple nodes. Shared operation ownership
coordinates account/PDS orchestration, verified recovery, mail and authentication.
Deployment lifecycle supplies bounded readiness and
draining, with repeatable single-node and replica checks.
Standard-tool migration, moderation coordination, fleet management and complete production qualification remain open; see implementation limits. Google/GitHub OIDC is roadmap work excluded from initial delivery.
Install Docker Compose v2, Node.js 24, Deno 2.8.3, Python 3, Git, Bash and flock
on the host. Application dependencies, builds and tests run in containers. Host
Node/Python support sandbox orchestration; do not run application npm commands
on the host.
For a repeatable isolated acceptance run:
./tests/local.sh freshnpm run test:e2e:atmosphere is an optional alias for shell orchestration. It does
not install or run the application on the host.
The harness creates a disposable pinned Atmosphere in a Box checkout, chooses an automatic subnet, installs this repository's stack templates, validates access metadata, builds images and runs the suites, with disruptive resilience checks last. It removes its own project and volumes afterward. Keep failed state for investigation with:
KEEP_FAILED_SANDBOX=1 ./tests/local.sh freshReports go to tests/artifacts/<project>. Migration in this suite exercises a
private synthetic source helper; it is not standard-tool migration acceptance.
For persistent development and selective commands, read testing.
The acceptance plans describe the repeatable checks and
link to current delivery requirements; historical passes are not new acceptance.
src/features/<feature>/ Operation, routes, pages and co-located tests
src/authentication/ Better Auth browser proof/session boundary
src/mail/ SMTP sending boundary and delivery
src/database/ Persistence ports, Drizzle adapters and fresh schemas
src/accounts/ Common account facts and proof primitives
src/pds/, src/plc/ Concrete protocol clients and authorized signing
src/http/, src/ui/ Shared HTTP and presentation helpers
src/app.mjs Explicit composition and route registration
src/main.mjs Startup, workers and shutdown
tests/ Contracts, browser journeys, fixtures and AiaB harness
Features own their operations end to end. Shared authentication, transactions and custody changes are coordinated; features never import each other's internals. The source boundary checker enforces this structure.
- Architecture and boundaries
- Data model and identity custody
- Reusable code, required work and investigations
- Delivery planning in Linear
- Testing and evidence limits
- Release notes and managed version preparation
- Agent and contributor rules
The application and Atmosphere in a Box harness were imported from the Entryway spike. The ePDS harness supplied the design pattern for disposable pinned checkouts, consumer-owned stacks, access metadata and scoped cleanup. Imported implementation and the required templates are now owned by this repository; earlier spike/replay trees are historical provenance, not additional runtime packages. Reference PDS behaviour is grounded in Bluesky's source and Entryway tests; no PDS fork is part of this repository. See the reuse assessment for source evidence.