lattice

The TypeScript project structure you'd eventually wish you'd started with.

┌─────────────────────────────────────────────────────────┐
│                     APP ROUTER                          │
│                    (pages only)                         │
└─────────────────────────────────────────────────────────┘
                           ▲
                                        │ one-way flow
                           │
┌─────────────────────────────────────────────────────────┐
│                      FEATURES/                          │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐              │
│   │ cart/    │  │ checkout/│  │ profile/ │   ← isolated │
│   │  ├─ api/ │  │  ├─ api/ │  │  ├─ api/ │              │
│   │  ├─ db/  │  │  ├─ db/  │  │  ├─ db/  │              │
│   │  └─ lib/ │  │  └─ lib/ │  │  └─ lib/ │              │
│   └──────────┘  └──────────┘  └──────────┘              │
│      ✗              ✗              ✗                    │
│      └──────────────┴──────────────┘                    │
│         no cross-feature imports                        │
└─────────────────────────────────────────────────────────┘
                           Urn="1" alt="" class="blkBorder img-share"/> Copy.▲
                           │
┌─────────────────────────────────────────────────────────┐
│                  GLOBAL (components/, lib/)             │
│              shared utilities & UI components           │
└─────────────────────────────────────────────────────────┘

  ESLint boundaries plugin enforces architecture at build time

---

What you get

Features that stay deletable. Each feature owns its api/, db/, lib/, and components/. No feature imports another. Ripping one out is rm -rf — no archaeology, no grep across the repo for lingering references.

Placement decisions made for you. "Where does this go?" has one answer per file. The linter rejects the wrong one. New contributors stop asking; reviewers stop arguing.

Refactors that don't snowball. One-way imports (global → feature → app) make cycles impossible by construction. Change a feature's internals freely; the blast radius is the feature.

Full feedback loop on day one. Vitest, Playwright, ESLint with boundaries, Prettier, TypeScript strict, and Lefthook pre-commit hooks are wired before you write a line. pnpm check:all runs the whole suite in parallel.

Why AI agents thrive here

Agents fail in large codebases for the same reasons junior engineers do — they can't see the whole repo, so they guess where code goes and whether something already exists. They guess hundreds of times a day. lattice removes the guessing.

• Wrong placement fails the build. The boundaries lint rule is a hard, immediate signal. An agent that imports across features sees the error in the same tool loop and corrects before the change ever reaches you.
• Predictable structure means reuse, not re-invention. A shared utility lives in src/lib/. A feature's data access lives in src/features/<name>/db/. Agents find existing code instead of writing a fifth version of it.
• Scoped context. Working on features/checkout/? That directory is the working set. No need to load the rest of the repo to reason about it.
• Deterministic conventions. shadcn under components/ui/, Tailwind v4 in styles/, e2e tests in e2e/. Less ambiguity, fewer hallucinated paths.

Quick start

git clone https://github.com/leviFrosty/lattice.git my-project
cd my-project
pnpm install
pnpm dev

Open http://localhost:3000.

Don't want the whole stack? Install a skill

If you don't want to clone the repo and all its dependencies, two installable agent skills let your AI assistant apply lattice on your behalf — pick the one that matches your situation:

lattice-refactor — for an existing project

Refactors an existing TypeScript project into the lattice feature-folder layout and wires up the same ESLint boundaries rules, Prettier, TypeScript strict, Vitest, and Lefthook setup. Uses a TDD red-green-refactor discipline so behavior is preserved at every step — no file moves without a green safety-net test. Framework-agnostic: works on Next.js, Vite, Remix, Nest, plain Node, etc.

npx skills@latest add https://github.com/leviFrosty/lattice/tree/main/skills/lattice-refactor

Then, in your agent of choice: "Use the lattice-refactor skill to migrate this project."

lattice-scaffold — for a new project

Bootstraps a brand-new TypeScript project with just the structural guardrails — ESLint boundaries plugin, Prettier, TypeScript strict, Vitest, Lefthook — and none of the framework choices. No Next.js, no Tailwind, no React. The output is an empty lattice-shaped skeleton where pnpm check:all is already green; you bring your own framework.

npx skills@latest add https://github.com/leviFrosty/lattice/tree/main/skills/lattice-scaffold

Then, in your agent of choice: "Use the lattice-scaffold skill to start a new project."

Both skills are self-contained — no other skills, plugins, or context required.

Project structure

src/
  app/              # Next.js App Router (pages only)
  features/         # Isolated feature modules
    feature-name/
      components/
      lib/
      db/
      api/
  components/       # Global UI (shadcn/ui under ui/)
  lib/              # Global utilities
  styles/           # Tailwind entrypoint
  e2e/              # Playwright tests

Rules the linter enforces: docs/project-structure.md.

Scripts

pnpm dev              # Dev server
pnpm build            # Production build
pnpm test             # Unit tests
pnpm test:e2e         # Playwright E2E
pnpm typecheck        # TypeScript
pnpm lint             # ESLint (incl. boundaries)
pnpm check:all        # fmt + lint + typecheck + test + build + e2e

Learn more

• Contributing
• Project Structure
• UI Components

License

MIT