spaceship / report

architecture / implementation + roadmap

classroom build · architecture and roadmap

Spaceship / architecture report

Spaceship IDE is the work of Chuanqi Sun. A Rough Idea adapts its access and model connections for classroom exploration. The original concept, flight deck, interaction design, and simulator remain credited to their author.

decision lab · owner panel · original MIT license

01 / First build

The public simulator needs no account or API key. Invited participants sign in with an emailed WorkOS code. Generation and decisions go through same-origin Vercel Functions; provider credentials remain on the server.

The owner can paste email addresses, revoke access, pause live requests, and set a lifetime demo allowance from $0 to $100. The initial allowance is $0. This is a small pilot with one roster, an owner role, and a participant role.

The decision lab runs the same context and question against different available decision models, showing structured answers, latency, and reported cost. Results stay in the page for comparison and disappear on navigation.

Deployment configuration, email delivery, and provider availability must be verified separately from a successful build. The interface reports when hosted access is not configured.

02 / Request path

BrowserVite / TypeScript
Public simulation
Model selection
→
Vercel FunctionsSession and roster
Allowance reservation
Request validation
→
OpenRouterStreaming generation
Typed decisions
Reported usage

WorkOS verifies the email address. Postgres on Neon stores roster membership, hashed revocable sessions, allowance, usage reservations, rate counters, and owner audit events. Server credentials are deployment secrets.

Routes: /api/auth, /api/session, /api/config, /api/generate, /api/decide, and /api/admin. The hosted base path is /. Preview deployments should use separate credentials and database branches.

03 / Access and allowance

  1. The owner adds invited emails. Adding an address does not send an email.
  2. The participant requests a sign-in code and enters it in the app.
  3. The server verifies the identity and checks active roster membership before issuing a 12-hour HttpOnly session.
  4. Each paid request rechecks membership and atomically reserves a conservative allowance estimate before contacting the provider.
  5. Reported cost settles the reservation once. Missing usage keeps the estimate reserved.

Revocation blocks subsequent requests. It cannot undo work already dispatched. There are per-user request and concurrency limits plus a shared concurrency limit. The owner can pause new requests immediately.

The allowance is cumulative, not a recurring monthly reset. Estimates and upstream billing can differ; provider-side limits provide an additional ceiling. Hosting, database, authentication, and provider credit fees are outside the model allowance. Class-scale load testing remains a follow-up.

04 / Model connections

Generation and decisions are distinct operations. Generation starts with OpenAI GPT OSS 120B and 20B through OpenRouter. The server discovers text decision models from OpenRouter's current catalogue, limited in this pilot to models with input-token pricing and no output or per-request charges.

Decision questions use rubric scores or yes/no probabilities. Every result is validated for the requested answer type and range. An available model may still refuse or lack compatible scoring; failures are shown explicitly. Alpha API and model availability can change.

Inputs are sent to OpenRouter and the selected provider. This app does not store prompts or generated text in its database. Model choices are saved in browser localStorage; API keys are not. Legacy browser keys are cleared when the app loads.

05 / Deferred until we learn from use

  • BYO provider keys, held in memory or a local proxy with explicit connection consent.
  • A local Ollama, LM Studio, or vLLM connection. A cloud Vercel function cannot reach a participant's localhost; a browser-to-loopback connection needs its own origin checks and setup.
  • Workshop dates, faculty groups, facilitator roles, per-person spending caps, roster import previews, and session-specific links.
  • Usage exports, retention controls, and broader operational monitoring.

These are design directions, not features of the first build. The owner panel intentionally stays small until classroom use reveals what is needed.

06 / Style and attribution

The flight deck keeps the original compact monospace, black-and-white palette, and orange interaction cues. The report, model lab, and admin panel use the same visual vocabulary with ordinary document layout for reading and forms.

extra/ is the author's design playground: style studies, pointer experiments, tray prototypes, illustrations, and sound tests. It is not the backend architecture guide.

The upstream README, citation, and MIT license remain included. This deployment is a classroom adaptation by A Rough Idea, not a claim of authorship of Spaceship IDE.

07 / References