OpenSEO backend code follows a three-layer architecture (TanStack server function → service → repository) with Zod validation at trust boundaries, idiomatic TypeScript throughout, and strict rules against mocking ORM chains and re-declaring production classes in tests. Test modules must import real classes statically, mock return values only in beforeEach, and use real SQL or service-level testing to catch refactors that break behavior; developers must log friction—retry loops, confusing setup, flaky commands—to .agents/PAPERCUTS.md immediately. A trust boundary is any point where data enters OpenSEO from an untrusted source (user input, external APIs, etc.); Zod validation at these boundaries prevents malformed or malicious data from propagating into service and repository layers.
For new application-backed backend functionality, the default layering convention is: TanStack server function → service → repository.[1] Idiomatic TypeScript is required throughout, and Zod must be used to validate untrusted data and narrow runtime values at trust boundaries.[1]
Tests must never re-declare a production class — the real class must be imported; if the module is too heavy to import, the class should be moved to a leaf module first (see ga4Errors.ts, gscErrors.ts).[1] ORM builder-chain mocking is banned in tests; repositories must be tested through services or real SQL evaluation, because chain mocks break on refactors that change no behavior.[1] Modules under test must be imported statically. vi.mock is hoisted, so per-test await import() and vi.resetModules() are banned unless module-level state must reset — and the reason must be commented.[1] beforeEach sets only default mock return values; Vitest's clearMocks already resets call state, so mockReset/mockClear ceremonies are banned.[1]
Any small, non-blocking repository friction encountered during development — retried tool calls, confusing setup steps, flaky commands, stale caches, or misleading errors — must be logged immediately to .agents/PAPERCUTS.md using the papercuts skill, without interrupting the current task.[1]
Sources