Skip to content

README.md

Latest commit

 

History

History
98 lines (74 loc) · 3.48 KB

README.md

File metadata and controls

98 lines (74 loc) · 3.48 KB
Raw

Boardit

Boardit is a full-stack Markdown note and publishing application being evolved into a trustworthy AI writing and private-knowledge portfolio project.

What works today

  • Private notes, folders, search, editing, version conflicts, and immutable revisions.
  • Public and unlisted publishing with author permalinks.
  • Rotating JWT refresh sessions with replay rejection and logout revocation.
  • OpenAPI-generated React Query client, deterministic CI, unit/integration tests, and Playwright smoke tests.
  • Versioned PostgreSQL/SQLite migrations plus outbox, job, AI-run, and candidate data boundaries.

The AI runtime, workers, retrieval, eval dashboard, and automatic indexing are foundations only—not implemented product features yet.

Stack

Layer Technologies
Frontend React 19, TypeScript, Vite 8, Tailwind CSS, React Query
Editor MDXEditor, CodeMirror, Markdown
Backend Go 1.24, Gin, GORM
Data PostgreSQL 15; SQLite for fast local tests
Contract OpenAPI, Orval-generated hooks and types
Testing Go test/race, Vitest, MSW, Playwright

Quick start

Prerequisites: Go 1.24+, Node.js 22, npm 10, and PostgreSQL 15+ or Docker.

# Database
docker compose up -d postgres

# Backend
cd backend
cp .env_sample .env
# Set DATABASE_DSN and a JWT_SECRET of at least 32 characters.
go run .

# Frontend, in a second shell
cd frontend
npm ci
npm run dev

Open http://localhost:5173. To run the frontend without the backend, use npm run dev:mock.

API startup applies pending versioned SQL migrations. Migration commands and rollback safety are documented separately; the application does not use AutoMigrate in its startup path.

Quality gates

# Backend
cd backend
test -z "$(gofmt -l .)"
go vet ./...
go test -race -p 1 ./...

# Frontend
cd frontend
npm ci
npm run lint
npm test
npm run build
npm run test:e2e

See testing strategy for change-specific requirements and generated-client checks.

Documentation

Need Document
Current system design Architecture
Durable technical decisions ADRs
Agent and contributor invariants AGENTS.md
Tests and CI Testing strategy
Database migration and rollback Migration runbook
Deployment and recovery Deployment runbook
AI and async data rules AI data boundaries
Shipping an AI feature AI feature playbook
Known gaps and decisions Known debt
Product modernization direction AI roadmap
Historical refactor evidence R0-R4 assessment

Backend- and frontend-specific setup is intentionally short and lives in backend/README.md and frontend/README.md.

Deployment

Docker Compose is the supported single-machine deployment model:

cp .env.docker.example .env
# Set POSTGRES_PASSWORD and JWT_SECRET.
docker compose up -d --build

Data persists in the postgres_data volume. Back up the database and review pending migrations before production upgrades. See the deployment runbook for update and recovery details. Push, deployment, domains, and production credentials are deliberately outside automated maintenance scope.