API Reference

Estrutura do Projeto

O Refstash é um monorepo gerenciado com pnpm workspaces. Abaixo está a estrutura completa do repositório — incluindo pastas de configuração de ferramentas que você pode não estar familiarizado.

locus-refs/

.agents/instruções para agentes de IA (ex: skills)

.claude/configuração do Claude Code

.cursor/

.zed/configuração do editor Zed

apps/aplicações do monorepo

web/Next.js 16 — app principal

src/

app/App Router — páginas e rotas de API

components/componentes React por feature

hook/TanStack Query hooks globais

lib/utilitários, config Tiptap, extensões

server/helpers server-side (requireSession)

styles/variáveis SCSS e animações

types/tipos TypeScript e schemas Zod

public/assets estáticos

Dockerfile

components.jsonconfiguração shadcn/ui

next.config.tsstandalone output, MDX, imagens

postcss.config.mjs

tsconfig.json

vitest.config.tsconfiguração de testes

collab/Hocuspocus — servidor WebSocket de colaboração (notas)

src/servidor Hocuspocus na porta 1234

Dockerfile

tsconfig.json

tldraw-sync/Cloudflare Worker — sync de canvas colaborativo (boards)

docs/documentação interna (ia.md, boards.md)

packages/

prisma/schema e migrations compartilhados

schema.prismamodelos do banco de dados

migrations/histórico de migrations

AGENTS.mdinstruções para agentes de IA

CLAUDE.mdinstruções para o Claude Code

GEMINI.mdinstruções para o Gemini

PLAN.mdplanejamento interno do projeto

README.md

biome.jsonlinter e formatter (substitui ESLint + Prettier)

.cz-config.jsconfiguração de commits semânticos (Commitizen)

.dockerignore

.env.example

.gitattributes

.gitignore

package.jsonscripts e dependências raiz

pnpm-lock.yamllockfile do pnpm — não editar manualmente

pnpm-workspace.yamldeclara os workspaces do monorepo

prisma.config.mjsconfiguração do Prisma CLI

skills-lock.jsonlockfile de skills de agentes de IA

Pastas de ferramentas de IA

Se você não tem experiência com agentes de IA, pode ignorar as pastas .agents/, .claude/, .cursor/ e os arquivos AGENTS.md, CLAUDE.md, GEMINI.md. São instruções de contexto para ferramentas como Claude Code, Cursor e Gemini CLI — não afetam o funcionamento da aplicação.

apps/web

O app principal. Next.js 16 com App Router, responsável pelo frontend e pela API REST. O build usa output: "standalone" — o Docker copia apenas os arquivos necessários para produção, resultando em imagens menores.

A estrutura interna de src/ segue uma divisão clara:

app/ — rotas de página e de API, organizadas por grupos (auth), (docs), (landing), (onboarding) e [workspaceSlug]
components/ — componentes React organizados por feature, com ui/ para shadcn e kibo-ui/ para componentes extras
hook/ — hooks globais de TanStack Query, um por recurso
lib/ — utilitários, configuração do editor Tiptap e extensões customizadas
server/ — helpers server-side como requireSession() e requireWorkspaceAccess()
types/ — tipos TypeScript (*.type.ts) e schemas Zod (*.schema.ts)

apps/collab

Servidor WebSocket construído com Hocuspocus para colaboração em tempo real nas notas. Roda na porta 1234 e se autentica via JWT gerado pela rota /api/collab/token do app web.

apps/tldraw-sync

Cloudflare Worker responsável pela sincronização em tempo real dos boards (canvas colaborativo). Usa o protocolo nativo do tldraw (TLSync) sobre WebSocket, com um Durable Object por board para manter o estado de sync em memória e persistir as shapes em SQLite embutido. Assets (imagens arrastadas para o canvas) são armazenados em um R2 bucket separado.

O projeto roda completamente na infraestrutura da Cloudflare — sem servidor Node.js próprio para os boards. Detalhes em Boards (Cloudflare).

prisma/

Schema e migrations ficam na raiz do monorepo e são compartilhados entre web e collab — ambos se conectam ao mesmo banco PostgreSQL. As migrations rodam automaticamente no startup do container web.

biome.json

O projeto usa Biome no lugar de ESLint + Prettier. Um único arquivo de configuração cobre lint e formatação para todo o monorepo.

Motivos App Router