Architecture Contract

The architecture contract is signed off for implementation start.

It does not claim that product runtime code exists. It does not claim that tests pass. Each wave must still earn runtime signoff.

Contract Meaning

contracted means the behavior and owner are clear enough to build.

blocked-by-gap means the owner is clear, but a named gap blocks signoff until the required proof exists.

deferred-post-parity means the surface is outside first parity.

Closed gaps in the current contract are design closures unless runtime proof is named. A design closure removes ambiguity. It does not replace implementation.

Fixed Decisions

Decision	Contract
Rewrite target	GoRunChat is a Go-native replacement for LibreChat behavior.
Predecessor role	LibreChat is read-only behavior evidence.
Backend foundation	Go uses net/http, chi, and selected libraries.
Web shell	templ and htmx own shell flows.
Live chat	Raw SSE and small JavaScript islands own streaming UI behavior.
Native mac	SwiftUI consumes a Go local service and shared contracts.
Codex	Rust stays authoritative through codex app-server.
t3code	t3code is reference-only.
First storage	MongoDB Atlas and Memorystore for Redis stay in first parity.
Later storage	Postgres, River, and pgvector wait until after parity.
Cache posture	Default to no cache or the narrowest viable revalidation.
Audit baseline	Application audit and immutable discovery records are first-class requirements.

Repo Roles

LibreChat defines tested product behavior for chat, streaming, files, MCP, auth, admin, config, and frontend flows.

Codex defines Rust execution and app-server protocol ownership. Go does not duplicate Codex session, config, plugin, sandbox, or login state logic.

t3code can inform event, projection, recovery, and UX patterns. It is not an implementation base.

Agent reference repos can inform provider SDK use. They do not define GoRunChat product behavior.

Runtime Surface Owners

• Go backend owns auth, admin, config, streams, providers, tools, MCP registry and app integration, files, messages, conversations, Mongo access, Redis coordination, and HTTP delivery.
• Web shell owns auth, startup, settings, admin, sidebar, navigation, and low-frequency mutations.
• Web islands own composer state, streaming controls, attachment widgets, MCP pickers, rich widgets, keyboard flows, and live message UI.
• Go local service owns the mac-facing transport and shared behavior boundary.
• SwiftUI owns native presentation and consumes Go-owned behavior.
• Rust Codex owns agent execution and Codex state.
• Go CLI work is limited to operational and admin wrappers if needed.

Proof Rules

All route tests must execute the mounted GoRunChat router or running service.

All browser tests must execute the composed GoRunChat web surface.

Shared DTOs must come from one Go-owned schema package and feed HTTP, web islands, local service, and SwiftUI adapters.

Mutating routes covered by the audit and discovery spine must fail closed when required records cannot be written.

No upstream test closes a GoRunChat runtime obligation by itself. Upstream evidence identifies behavior to preserve or intentionally correct.

Replacement Spec Closures

The replacement spec fixes the known blocker surfaces:

• Message writes use path-scoped and conversation-bound rules.
• Responses transport owns stored response ids, continuation, retrieval, and usage persistence.
• Admin proof runs through the mounted admin route tree.
• LDAP config shapes are fixed for disabled, enabled, and username-mode states.
• Auth, startup, settings, navigation, composer, widgets, artifacts, and accessibility require browser-owned proof.
• Shared SSE, search, and ACL DTOs use one narrowed generated contract.

Use these closures to build. Do not present them as runtime proof until the named tests pass.