Documentation

Structure du projet

Comment Motoko Base est organisé.

Motoko Base sépare les routes du code produit. Les routes dans src/app/ restent fines ; tout ce que vous construisez vit dans src/features/.

Vue d’ensemble des répertoires

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/` — routes uniquement

Les pages doivent composer du code de features, pas contenir de logique métier :

// 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} />;
}

Utilisez des Route Handlers (app/api/...) pour le catch-all d’auth, les webhooks et les endpoints de streaming. Utilisez des Server Actions dans les features pour le CRUD.

`features/` — votre produit

Chaque feature est un dossier autonome. Regardez links, storage ou settings pour des exemples réels.

Structure typique :

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/` — infrastructure partagée

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

Les tables de base de données vivent dans lib/db/schema/. Exportez les nouvelles tables depuis lib/db/schema/schema.ts.

`components/` et configuration du dashboard

Ajouter un composant shadcn → components/ui/
Ajouter un élément de navigation → features/dashboard/config/nav.ts
Ne mettez pas d’UI spécifique à une feature ici — gardez-la dans le dossier de la feature.

Règles empiriques

Server-first — l’auth et l’accès à la base restent côté serveur
Ownership — chaque mutation utilise id + userId
Validation — Zod à la frontière serveur (actions et route handlers)
Soft-fail — les intégrations optionnelles (billing, R2, AI) ne doivent pas faire planter des pages non liées
Copiez, n’abstrayez pas — dupliquez une feature démo et éditez-la ; pas de couches de framework

Pour les règles orientées agents, voir AGENTS.md à la racine du dépôt.

Prochaines étapes

Installation — si vous n’avez pas encore configuré le projet.

Introduction — aperçu de ce qui est livré dans le starter.

Vue d’ensemble des répertoires

app/ — routes uniquement

features/ — votre produit