Runtime topologies and technology placement
The same contracts appear in several process graphs; local CLI, hosted web, Electron, and mobile move ownership without moving repository execution off the environment server.
What this chapter resolves
- Draw the process and trust boundary for every execution client.
- Separate product UI families from delivery and publication shapes.
- Explain technology placement as verified mechanics or explicitly labeled inference.
There is no single “T3 Code process.” The invariant is an environment server that owns authoritative repository/provider execution. What changes by product shape is who launches that server, where the renderer runs, how it reaches the endpoint, and which device-local systems surround the shared semantics.
Move the same thread through four topologies
Select a delivery shape to see process and trust ownership.
Scenario 1 of 4: npx t3
One CLI process serves API and copied web assets
The published npm package starts the local server and serves a web build copied into its distribution.
- Browser and server communicate over loopback HTTP/WebSocket.
- Repository, provider, Git, files, and PTY stay in the server process/environment.
- Closing the foreground server ends the local environment unless a managed launcher owns it.
- npx t3 · One CLI process serves API and copied web assets (Expected path)
The published npm package starts the local server and serves a web build copied into its distribution.
- Browser and server communicate over loopback HTTP/WebSocket.
- Repository, provider, Git, files, and PTY stay in the server process/environment.
- Closing the foreground server ends the local environment unless a managed launcher owns it.
apps/server/scripts/cli.ts:143–176↗apps/server/src/server.ts:123–472↗ - Hosted web · Static React client connects to registered environments (Alternative)
The hosted app has no colocated repository server; cloud identity and pairing resolve remote environment endpoints.
- Application traffic ultimately targets the environment endpoint.
- The hosted page never receives local filesystem authority merely by loading.
- Browser history and hosted authentication are selected at runtime.
apps/web/src/main.tsx:21–59↗docs/internals/overview.md:5–28↗ - Electron · Main process supervises renderer and backend pool (Caveat)
Electron bundles the web renderer and manages primary/WSL servers, SSH, exposure, preview, native menus, telemetry, and updates.
- The renderer receives a curated contextBridge API, not raw Node.
- Server bootstrap and resource-control channels cross dedicated file descriptors.
- Desktop can own several backend processes while each remains its own environment authority.
apps/desktop/src/app/DesktopApp.ts:142–291↗apps/desktop/src/preload.ts:30–185↗ - Mobile · React Native is remote-only but not merely a web wrapper (Alternative)
Expo clients reuse connection/state semantics and implement native feed, terminal, share, persistence, notification, and OTA behavior.
- No provider or T3 server is bundled on the phone.
- Offline task intent is a device-local durable outbox.
- iOS and Android capability edges differ.
apps/mobile/app.config.ts:159–180↗apps/mobile/src/state/use-thread-outbox-drain.ts:285–424↗apps/mobile/src/features/settings/SettingsRouteScreen.logic.ts:1–8↗
Technology placement, not mythology
| Technology | Placement | Verified consequence |
|---|---|---|
| Effect + Schema | contracts, server services/scopes, client runtime | runtime-decoded boundaries, typed failure channels, scoped child resources, composable layers |
| SQLite | environment server | one transactional event/projection/accepted-receipt store plus indexed query models |
| React | shared web renderer | one UI serves local browser, hosted app, and Electron with runtime-specific composition |
| Electron | desktop main/preload | OS/backend/update/preview authority stays outside the sandboxed renderer |
| React Native + Expo | iOS/Android | native persistence, navigation, modules, stores, and OTA use a separate release domain |
| Ghostty | WASM on web; native modules on mobile | terminal semantics are shared conceptually while rendering/input paths remain platform-specific |
| Astro | marketing site | download/publication pages build independently of the React product client |
Marketing is the fifth delivery shape, not a fifth client
The independent Astro marketing site discovers stable downloads and links to app
stores. It does not load client-runtime, connect to environments, or render thread
state. Counting it clarifies release/distribution ownership; placing it in the
execution topology would confuse publication with control.