85 lines
3.6 KiB
Markdown
85 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```sh
|
|
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.litenote.li212.fr)
|
|
├── 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/`
|