workspace-md

Workspace colaborativa markdown-first com múltiplas vistas para navegação e organização de notas. Inspirado na estética do Obsidian — interface escura, monocromática e minimalista.

Status: Beta — em desenvolvimento ativo. Funcionalidades Core ✅, vistas adicionais em construção.

---

O que é

workspace-md é uma aplicação web onde documentos Markdown são a unidade central de organização. Cada documento vive numa workspace e pode ser visualizado de quatro formas diferentes:

Vista	O que mostra
Notes	Lista de todos os documentos + editor com preview
Board	Kanban agrupado por status (backlog → done)
Calendar	Documentos organizados por data de início e entrega
Graph	Grafo de links entre documentos (wikilinks [[...]])

O conteúdo é parsed e indexado a partir de frontmatter YAML dentro de cada documento:

---
type: task
status: doing
tags: [backend, api]
assignee: João
start: 2026-04-01
due: 2026-04-10
---

## Título do Documento

Corpo do markdown...

---

Arquitetura

workspace-md/
├── apps/
│   └── web/                     # Next.js 15 (App Router)
├── packages/
│   ├── db/                     # Schema Drizzle ORM + PostgreSQL
│   ├── markdown-core/           # Parser de frontmatter e wikilinks
│   └── shared/                 # Types, enums, schemas Zod
├── infra/docker/               # Docker Compose (PostgreSQL)
└── docs/                       # Arquitetura e planos

Stack

Camada	Tecnologia
Framework	Next.js 15.2 + React 19 + TypeScript 5.8
Database	PostgreSQL 16 via Drizzle ORM
Auth	Better Auth (email/password, sessões de 7 dias)
Styling	Tailwind CSS 3.4 (dark mode, grayscale)
Testing	Vitest

---

Pacotes

@workspace-md/web

Aplicação Next.js principal. Estrutura de páginas:

app/
├── (auth)/login/                # Login
├── admin/                       # Painel admin
├── api/
│   ├── auth/[...all]/           # API Better Auth
│   ├── admin/users/             # Gestão de utilizadores
│   └── health/                  # Health check
└── w/[workspaceSlug]/           # Workspace
    ├── notes/                   # Lista + editor de documentos
    ├── board/                   # Vista Kanban
    ├── calendar/                # Vista de calendário
    └── graph/                   # Grafo de links

@workspace-md/db

Schema Drizzle com tabelas para:

• users, sessions, accounts — autenticação
• workspaces, workspace_members — workspaces e membros
• documents — central de documentos (título, slug, content_md, frontmatter JSONB, tipo, status, tags, datas, etc.)
• document_links — links wikilink entre documentos
• document_revisions — histórico de versões
• comments, presence, activity_events, attachments — funcionalidades adicionais

@workspace-md/markdown-core

Biblioteca de parsing de markdown:

parseFrontmatter(markdown)     // Extrai YAML frontmatter
buildDocumentProjection(fm)    // Normaliza tipo, status, tags, datas
extractWikilinks(markdown)     // Extrai [[links]] com posição
parseDocument(markdown)        // Parser completo do documento

@workspace-md/shared

Enums de tipo e status de documento, schemas Zod de validação, constantes partilhadas.

---

Convenções de Documento

Frontmatter reservado

Campo	Valores	Uso
type	note, task, project, meeting, event, reference, person	Classificação
status	backlog, todo, doing, blocked, done, cancelled	Estado Kanban
tags	array de strings	Etiquetas livres
assignee	nome	Responsável
start	YYYY-MM-DD	Data de início
due	YYYY-MM-DD	Data de entrega

Wikilinks

[[Nome do Documento]]           → link para o documento
[[Nome do Documento|Alias]]     → link com alias

Links não resolvidos (documento que não existe) são guardados como resolved: false em document_links.

Título

O título do documento é guardado no campo title da base de dados — não como H1 no body markdown. O H1 dentro do body é opcional e apenas para renderização.

---

Configuração

Variáveis de ambiente

Copie .env.example para .env na raiz:

cp .env.example .env

Edite com os seus valores:

DATABASE_URL=postgresql://postgres:sua_senha@localhost:5432/workspace_md
AUTH_SECRET=minimo_32_bytes_aleatorios  # openssl rand -base64 32 | tr -d '\n'
NEXT_PUBLIC_APP_URL=http://localhost:3000

Nota: O .env está ignorado pelo git. Nunca cometa segredos.

Preparar a base de dados

# 1. Instalar dependências
pnpm install

# 2. Iniciar o PostgreSQL (Docker)
pnpm db:up

# 3. Criar/push schema (desenvolvimento — não apaga dados)
pnpm db:push

# 4. (Opcional) Gerar migrations formais
pnpm db:generate
pnpm db:migrate

Iniciar o dev server

pnpm dev

Aplicação disponível em http://localhost:3000.

---

Scripts Disponíveis

pnpm dev           # Dev server
pnpm build         # Build de produção
pnpm start         # Iniciar em produção
pnpm typecheck     # Verificação de tipos TypeScript
pnpm test          # Testes Vitest
pnpm db:up         # Iniciar PostgreSQL (Docker)
pnpm db:down       # Parar PostgreSQL
pnpm db:push       # Push schema para DB
pnpm db:generate   # Gerar migrations Drizzle
pnpm db:migrate    # Aplicar migrations

---

Design Visual

• Paleta: Escala cinza pura — #0a0a0a a #f5f5f5
• Bordas: 1px solid gray-800 — separadores subtis sem sombras
• Tipografia: Varições de peso (font-semibold vs font-normal) em vez de cores para hierarquia
• Sem cores de destaque — toda a UI usa apenas tons de cinza
• Dark mode first — o app é inteiramente escuro

---

Desenvolvimento

Estrutura de um feature

Cada domínio vive em features/ com estrutura própria:

features/documents/
├── components/        # Componentes React UI
├── lib/               # Lógica pura (parsing, formatação)
├── server/            # Server actions + funções server-side
│   ├── server/        # Services e repositories
│   └── *.action.ts    # Server actions
└── *.test.tsx         # Testes

Server Actions

Operações de escrita passam por Server Actions (ficheiros *.action.ts em server/). Validação com Zod, erros tipados com AppError.

Cache e Performance

• ISR: Páginas de workspace (board, calendar, graph, notes) usam revalidate = 60
• Prefetch: Links de navegação lateral e da lista de notas pré-carregam rotas
• Dynamic imports: Componentes pesados (editor CodeMirror, DocumentPreview) carregados sob demanda
• Memoization: useMemo nos filtros de board/calendar, React.memo no DocumentPreview
• Streaming: loading.tsx com Suspense para transições suaves

---

Funcionalidades Implementadas

• Autenticação email/password via Better Auth
• Workspaces com múltiplos membros e roles (owner/admin/member)
• CRUD completo de documentos
• Editor Markdown com autosave, preview e raw mode
• Parsing automático de frontmatter (tipo, status, tags, datas)
• Wikilinks [[...]] com resolução automática de links
• Vista Board (Kanban por status)
• Vista Calendar (por data de início/entrega)
• Vista Graph (relações entre documentos)
• Sistema de tags e filtros
• Revisões de documento (histórico)
• Painel admin para gestão de utilizadores
• Health check API com verificação de DB
• Error boundaries e loading skeletons

---

Roadmap

• Comentários em documentos
• Notificações e presença real-time
• Busca full-text
• Attachments com S3
• convites por email para workspaces
• Mobile responsive refinamentos
• Deploy com Docker

---

Requisitos

• Node.js 20+
• pnpm 10+
• Docker (para PostgreSQL) ou PostgreSQL 16 acessível
• Git