CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Remanso is a Vue 3 + TypeScript web app that displays markdown notes from GitHub repositories with Zettelkasten-style backlinks. Users access notes via https://remanso.space/{user}/{repo}. Also supports decentralized public notes via ATProto (Bluesky) at /notes/:did/:rkey. Supports both public repos (direct access) and private repos (GitHub OAuth).

Commands

pnpm dev          # Start development server
pnpm build        # Production build
pnpm test         # Run Vitest tests (no config file, uses defaults)
pnpm lint         # ESLint with auto-fix
pnpm types        # TypeScript type-check

Run a single test file: pnpm test src/modules/repo/services/resolvePath.spec.ts

Architecture

Tech Stack

Vue 3 (3.5) with Composition API, Pinia for state, Vue Router
Vite 7 build tool, TypeScript strict mode
Tailwind CSS v4 + DaisyUI v5 for styling (PostCSS plugin approach, not tailwind.config.js)
TanStack Vue Query + ts-rest + arktype for typed API contracts
PouchDB (IndexedDB) for local persistence
Octokit for GitHub API integration
markdown-it with plugins (KaTeX, Shikiji, Mermaid, checkboxes, GitHub alerts)

Styling

Tailwind v4 uses the modern CSS-based config in src/styles/app.css:

@import "tailwindcss" instead of directives
DaisyUI configured via @plugin 'daisyui' { themes: retro --default, coffee --prefersdark; }
@tailwindcss/typography for prose styling

Directory Structure

src/
├── views/           # Page components (FluxNoteView, FleetingNotes, etc.)
├── components/      # Reusable UI components
├── modules/         # Feature domains
│   ├── note/        # Note models, hooks, caching
│   ├── repo/        # GitHub repo integration (Pinia store, Octokit service)
│   ├── user/        # Authentication, user settings
│   ├── card/        # Spaced repetition
│   ├── history/     # Edit history tracking
│   ├── atproto/     # ATProto/Bluesky integration (DID resolution, blob URLs)
│   └── post/        # ts-rest API client for public note publishing (api.remanso.space)
├── hooks/           # Composition hooks (useMarkdown, useBacklinks, useGitHubContent, etc.)
├── data/            # PouchDB wrapper and data models
├── utils/           # Utilities including custom markdown-it plugins
├── locales/         # i18n (English/French)
└── bus/             # Event buses for inter-component communication

Key Routes

/ - Home
/:user/:repo - Main note view (FluxNoteView) with stacked notes
/:user/:repo/inbox|draft|todo|history - Specialized note views
/notes - Public note list (ATProto-based)
/notes/:did/:rkey - Single public note view

Key Files

src/router/router.ts - Route definitions
src/modules/repo/store/userRepo.store.ts - Central Pinia store for repo/file state
src/modules/repo/services/octo.ts - Octokit wrapper for GitHub API
src/hooks/useMarkdown.hook.ts - Markdown rendering with all plugins
src/modules/post/data/client.ts - ts-rest API contract definitions with arktype validation
src/data/data.ts - PouchDB database wrapper

Patterns

All components use Composition API (<script setup lang="ts">)
Custom hooks encapsulate feature logic (use*.hook.ts or use*.ts)
Event buses (noteEventBus, backlinkEventBus) for cross-component communication
ts-rest contracts use arktype schemas for request/response validation
Path alias: @ maps to src/

3.6 KiB Raw Permalink Blame History