Dokumentation

Projektstruktur

Wie Motoko Base organisiert ist.

Motoko Base trennt Routen von Produktcode. Routen in src/app/ bleiben dünn; alles, was Sie bauen, lebt in src/features/.

Verzeichnisübersicht

src/
├── app/           # Next.js routes — layouts, pages, API handlers
├── features/      # Product features (UI, actions, queries, schemas)
├── components/    # Shared UI — shadcn primitives + dashboard shell
├── lib/           # Shared infrastructure (auth, db, billing, email, …)
└── assets/        # Static images and logos

Folder	Purpose
`app/`	URL structure only. Fetch data, check auth, render a feature component.
`features/`	Where your SaaS logic lives — one folder per feature.
`components/ui/`	Reusable shadcn/ui primitives (Button, Card, Dialog, …).
`components/layout/`	Dashboard shell, sidebar, headers — shared across pages.
`lib/`	Server-only infrastructure. Features call into `lib/`, not the other way around.
`features/dashboard/config/`	Dashboard sidebar and settings navigation (`nav.ts`, `settings-nav.ts`).
`assets/`	SVG logos, images — imported where needed.

`app/` — nur Routen

Seiten sollten Feature-Code komponieren, keine Business-Logik enthalten:

// src/app/dashboard/links/page.tsx
import { LinksPage } from "@/features/links/components/links-page";
import { listLinksForUser } from "@/features/links/queries";
import { getCachedSession } from "@/lib/auth/session";

export default async function Page() {
  const session = await getCachedSession();
  const result = await listLinksForUser(session!.user!.id);
  return <LinksPage initialLinks={result.items} />;
}

Verwenden Sie Route Handlers (app/api/...) für Auth-Catch-all, Webhooks und Streaming-Endpoints. Verwenden Sie Server Actions innerhalb von Features für CRUD.

`features/` — Ihr Produkt

Jedes Feature ist ein eigenständiger Ordner. Schauen Sie sich links, storage oder settings für echte Beispiele an.

Typisches Layout:

src/features/my-feature/
├── components/     # Page UI and sub-components
├── actions.ts      # Server Actions ("use server")
├── queries.ts      # Database reads
├── schemas.ts      # Zod validation
├── config.ts       # Constants, limits, feature flags
└── lib/            # Feature-specific helpers (optional)

`lib/` — gemeinsame Infrastruktur

Module	What it provides
`lib/auth/`	Better Auth, session helpers
`lib/db/`	Drizzle client and table schemas
`lib/billing/`	Provider-agnostic billing API
`lib/email/`	Resend, templates
`lib/analytics/`	PostHog events
`lib/monitoring/`	Sentry

Datenbanktabellen liegen in lib/db/schema/. Exportieren Sie neue Tabellen aus lib/db/schema/schema.ts.

`components/` und Dashboard-Konfiguration

Eine shadcn-Komponente hinzufügen → components/ui/
Einen Nav-Eintrag hinzufügen → features/dashboard/config/nav.ts
Legen Sie keine feature-spezifische UI hier ab — behalten Sie sie im Feature-Ordner.

Faustregeln

Server-first — Auth und Datenbankzugriff bleiben auf dem Server
Ownership — jede Mutation verwendet id + userId
Validierung — Zod an der Server-Grenze (Actions und Route Handlers)
Soft-fail — optionale Integrationen (Billing, R2, AI) dürfen unabhängige Seiten nicht crashen
Kopieren, nicht abstrahieren — ein Demo-Feature duplizieren und anpassen; keine Framework-Schichten

Für agentenorientierte Regeln siehe AGENTS.md im Repository-Root.

Nächste Schritte

Installation — falls Sie das Projekt noch nicht eingerichtet haben.

Einführung — Überblick darüber, was im Starter mitgeliefert wird.

Verzeichnisübersicht

app/ — nur Routen

features/ — Ihr Produkt