MOTOKO BASE

Documentação

Estrutura do projeto

Como o Motoko Base está organizado.

Abrir emChatGPT (abre em uma nova aba)Claude (abre em uma nova aba)Cursor (abre em uma nova aba)Como o Motoko Base está organizado.

O Motoko Base separa rotas do código de produto. As rotas em src/app/ ficam enxutas; tudo o que você constrói vive em src/features/.

Visão geral dos diretórios

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
FolderPurpose
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/ — apenas rotas

As páginas devem compor código de features, não conter lógica de negócio:

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

Use Route Handlers (app/api/...) para o catch-all de auth, webhooks e endpoints de streaming. Use Server Actions dentro das features para CRUD.

features/ — seu produto

Cada feature é uma pasta autocontida. Veja links, storage ou settings para exemplos reais.

Layout 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/ — infraestrutura compartilhada

ModuleWhat 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

As tabelas do banco ficam em lib/db/schema/. Exporte tabelas novas a partir de lib/db/schema/schema.ts.

components/ e configuração do dashboard

  • Adicionar um componente shadcn → components/ui/
  • Adicionar um item de navegação → features/dashboard/config/nav.ts
  • Não coloque UI específica de feature aqui — mantenha na pasta da feature.

Regras práticas

  • Server-first — auth e acesso ao banco ficam no servidor
  • Ownership — toda mutation usa id + userId
  • Validação — Zod na fronteira do servidor (actions e route handlers)
  • Soft-fail — integrações opcionais (billing, R2, AI) não devem derrubar páginas não relacionadas
  • Copie, não abstraia — duplique uma feature demo e edite; sem camadas de framework

Para regras orientadas a agentes, veja AGENTS.md na raiz do repositório.

Próximos passos

Instalação — se você ainda não configurou o projeto.

Introdução — visão geral do que vem no starter.