Work

Architectures

My engineering playbook: opinionated architectures for Next.js, TanStack Start and NestJS, shipped as Claude Code plugins, so every project and every agent works from the same patterns. It began in March 2026 as a template of Giga Psych’s architecture.

Year
2026 — present
template in March, public in August
Role
Solo
doctrine, plugins, tooling
Type
Developer tooling
Claude Code plugins
Access
Open source · MIT
Stack
View on GitHub

Overview

How I build software, written down once and installed into every project that follows it.

Each architecture is a set of rules and patterns for one stack: the folder layout, the data layer, auth, forms, components and the rules that must never be broken. Around them sit the tools that keep a project on them: skills that load the right rules when the work touches them, agents that scaffold and audit, and hooks that remind.

It started as a template of my own code and grew into three stacks, two for the frontend and one for the backend. People and agents read the same doctrine, so a project built with Claude Code looks the way I would have written it.

It’s still under maintenance: I polish the repository in my free time, and any contribution is appreciated.

The architectures

Three stacks, each from a different source: one from code I wrote by hand, one translated from it, and one from the framework’s own guidance.

Derived from Giga Psych
Next.js
Written down from the frontend I built by hand for Giga Psych: the route groups, the proxy to the backend, a folder of the same files for every resource, TanStack Query on the server and the client, URL state with nuqs, and shadcn-style composition. Every rule in it was a working pattern first.
  • Zod schemas at every API boundary, with types inferred from them.
  • TanStack Query is the only caching layer: no fetch cache, ISR or revalidateTag.
  • Server actions return a Result instead of throwing.
  • Services are organised by backend domain, and pages keep their components beside them.
  • The browser never talks to a backend: API routes proxy every call.
Ported from Next.js
TanStack Start
Translated from the Next.js architecture pattern by pattern, with a migration guide that maps each one: the proxy becomes server functions, a resource’s actions and queries merge into one file, middleware becomes beforeLoad. Since then it has been kept in sync with TanStack’s official documentation as the framework changed, and it is the stack that gets new conventions first.
  • Server functions instead of a proxy: createServerFn replaces the API routes.
  • URL state is TanStack Router’s typed search params: a Zod schema in validateSearch, no extra library.
  • The Start session is the source of truth for auth; backend tokens stay on the server.
  • Flat, dot-named files per resource: {resource}.schema.ts, {resource}.functions.ts.
  • No React Server Components directives: no “use client” or “use server”.
  • shadcn on Base UI, not Radix.
From the official patterns
NestJS
Built entirely from NestJS’s official patterns and documentation, not from a project of mine: a modular monolith where each part of the domain is a module, with its own data, events and jobs, and a typed contract for the frontends.
  • A modular monolith: each part of the domain is a NestJS module, not a microservice.
  • Modules never import each other’s internals; they talk through domain events.
  • Two processes from one image: HTTP and WebSockets in one, BullMQ workers in the other.
  • Zod for every DTO, instead of class-validator decorators.
  • The OpenAPI spec is the contract, and typed clients are generated from it.

The plugins

The repository is a Claude Code plugin marketplace. Projects install the architectures instead of copying them, so one update brings the latest rules, skills and agents to every project at once.

  • Skills

    Rules that load when needed

    Eight doctrine skills, for services, state, UI, auth, forms, modules, decisions and contributing. Each loads only when the work touches its area, and reads the stack from package.json, so one set serves all three architectures.

  • Agents

    Scaffold and audit

    Each frontend stack ships fourteen agents: they plan a migration, scaffold pages, services and widgets, review a project against the architecture, and catch a useQuery that should suspend or a colour that isn’t a token.

  • Hooks

    Reminders after edits

    After an agent edits a file, a hook reminds it of the rules for that kind of file. They are advice, not gates: the checks that must hold run in the project’s CI.

  • Sync

    Know what a project runs

    A script reports which plugins a project has and whether each is current, behind or missing; an audit agent judges what a script can’t, like a local fork of an agent or a rule that drifted.

  • arch-coreThe doctrine skills, the drift audit and every stack’s reference; the others need it
  • arch-nextjsNext.js agents, hooks and a settings template
  • arch-tanstack-startTanStack Start agents, hooks and a settings template
  • arch-nestjs-backendNestJS doctrine, with module scaffolding and audit agents
  • product-designA prototyping skill, visual-language doctrine and a review agent for rendered pages

Install

Add the marketplace once, then install the plugin for the project’s stack. Here, TanStack Start:

claude plugin marketplace add exx0dusss/architecturesclaude plugin install arch-tanstack-start@architectures --scope project
Open in Claude

Or let an agent do it: Copy prompt gives Claude Code the steps to pick the plugin for your stack and install it, and Open in Claude starts a chat that reads the repository and helps you choose.

--scope project writes the plugin into the project’s .claude/settings.json, so everyone who clones it gets the same architecture from git. Then run /arch-init once for what a plugin can’t do by itself: the project’s own AGENTS.md index, permissions and component registry. claude plugin update brings later versions.

Codex installs the same skills from the repository’s own Codex marketplace.

History

From the private history and the public repository.

  1. 24 Mar 2026
    A template of Giga Psych
    Next.js · Claude Code agents
    Giga Psych’s frontend architecture, written down as the Next.js stack with its building blocks and file templates; by midnight, the first Claude Code agents.
  2. 25 Mar 2026
    TanStack Start
    TanStack Start · Base UI
    The Next.js stack, translated to TanStack Start the next night, and SalonSvitlo’s storefront started from it.
  3. Apr 2026
    NestJS
    NestJS · Drizzle · BullMQ
    A backend architecture from NestJS’s own patterns, with new agents beside it.
  4. Aug 2026
    Plugins and decisions
    Claude Code plugins
    The architectures shipped as Claude Code plugins on 17 August, and a log of architecture decisions began the next day.
  5. 28 Aug 2026
    Open source
    Published under MIT with a fresh history. Giga Psych now installs it back, like any other project.

Design

This page is drawn on a cutting mat.

  • Drafting white#ffffff
  • Mat green#0f7f74
  • Deep mat#0b3b36

Architectures is where plans are drawn before anything is built, so its page borrows the green of a designer’s cutting mat: the surface under every careful line, marked with a grid you can measure against.

White drafting paper takes up most of the gradient and the green runs through it like the mat showing at the edges, quiet and precise, a colour that says “measure twice”. The avatar is the same green: a blueprint on a blob of mat.

Next project
SalonSvitlo