Documentación

Estructura del proyecto

Cómo está organizado Motoko Base.

Motoko Base separa las rutas del código de producto. Las rutas en src/app/ se mantienen delgadas; todo lo que construyes vive en src/features/.

Vista general de directorios

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/` — solo rutas

Las páginas deben componer código de features, no contener lógica de negocio:

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

Usa Route Handlers (app/api/...) para el catch-all de auth, webhooks y endpoints de streaming. Usa Server Actions dentro de las features para CRUD.

`features/` — tu producto

Cada feature es una carpeta autocontenida. Mira links, storage o settings para ejemplos reales.

Diseño típico:

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/` — infraestructura compartida

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

Las tablas de la base de datos viven en lib/db/schema/. Exporta tablas nuevas desde lib/db/schema/schema.ts.

`components/` y configuración del dashboard

Añadir un componente shadcn → components/ui/
Añadir un ítem de navegación → features/dashboard/config/nav.ts
No pongas UI específica de una feature aquí — mantenla en la carpeta de la feature.

Reglas prácticas

Server-first — auth y acceso a la base de datos se quedan en el servidor
Ownership — cada mutación usa id + userId
Validación — Zod en el límite del servidor (actions y route handlers)
Soft-fail — las integraciones opcionales (billing, R2, AI) no deben tumbar páginas no relacionadas
Copia, no abstragas — duplica una feature demo y edítala; sin capas de framework

Para reglas orientadas a agentes, consulta AGENTS.md en la raíz del repositorio.

Siguientes pasos

Instalación — si aún no has configurado el proyecto.

Introducción — resumen de lo que incluye el starter.

Vista general de directorios

app/ — solo rutas

features/ — tu producto