From be044ef941bed21b64250a38583dc09ed24727ca Mon Sep 17 00:00:00 2001 From: patrick Date: Thu, 5 Mar 2026 15:18:09 -0500 Subject: [PATCH] create documentation --- README.md | 202 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 176 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index ba0f94e..fc7be66 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,192 @@ -# sv +# Bullseye -Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli). +A modern, real-time personal productivity application built with Svelte 5 and SvelteKit. Bullseye helps you build better habits and capture your thoughts with a fast, offline-first experience that syncs across all your devices. -## Creating a project +## Features -If you're seeing this, you've probably already done this step. Congrats! +- **Habit Tracking** - Build and maintain daily habits with a visual calendar grid, numeric tracking, and progress insights +- **Notes** - Capture thoughts with a markdown editor, organize with tags, and find anything with full-text search +- **Real-time Sync** - All your data syncs instantly across devices with offline support +- **Dark Mode** - Full light/dark theme support with customizable primary colors -```sh -# create a new project -npx sv create my-app +### Planned Features + +- Tasks/Todos with due dates and priorities +- Long-term reminders with push notifications + +## Tech Stack + +| Category | Technology | +|----------|------------| +| Framework | Svelte 5 + SvelteKit | +| Language | TypeScript (strict mode) | +| Styling | Tailwind CSS 4 | +| UI Components | shadcn-svelte (Bits UI) | +| Database | Triplit (real-time sync) + SQLite (authentication ) | +| Authentication | Better Auth | +| Markdown | Carta-md with Shiki syntax highlighting | + +## Getting Started + +### Prerequisites + +- Node.js 18+ +- pnpm (recommended) or npm + +### Installation + +```bash +# Clone the repository +git clone https://github.com/yourusername/bullseye-app.git +cd bullseye-app + +# Install dependencies +pnpm install ``` -To recreate this project with the same configuration: +### Environment Setup -```sh -# recreate this project -pnpm dlx sv create --template minimal --types ts --add prettier eslint vitest="usages:unit,component" tailwindcss="plugins:none" sveltekit-adapter="adapter:node" drizzle="database:sqlite+sqlite:better-sqlite3" better-auth="demo:password" mcp="ide:claude-code+setup:local" --install pnpm ./ +Create a `.env` file in the project root: + +```env +# SQLite database for auth +DATABASE_URL=local-drizzle.db + +# App URL +ORIGIN="http://localhost:5173/" + +# Better Auth secret (generate a 32-character random string) +BETTER_AUTH_SECRET="your-secret-key-here" + +# Triplit configuration +LOCAL_DATABASE_URL="local-triplit.db" +PUBLIC_TRIPLIT_SERVER_URL="your-triplit-server-url" +PUBLIC_TRIPLIT_TOKEN="your-triplit-token" ``` -## Developing +### Database Setup -Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server: - -```sh -npm run dev - -# or start the server and open the app in a new browser tab -npm run dev -- --open +```bash +# Push schema to database +pnpm run db:push ``` -## Building +### Running Dev Server -To create a production version of your app: - -```sh -npm run build +```bash +# Start development server +pnpm run dev +# Start triplit development server +pnpm triplit dev ``` -You can preview the production build with `npm run preview`. +## Project Structure -> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment. +``` +src/ +├── lib/ +│ ├── api/ # Data layer (Triplit CRUD operations) +│ ├── components/ # Reusable Svelte components +│ │ └── ui/ # shadcn-svelte component library +│ ├── context/ # State services (Svelte 5 runes) +│ ├── server/ # Server-only code (auth, database) +│ ├── triplit/ # Triplit client and schema definitions +│ └── utils.ts # Utility functions +├── routes/ +│ ├── (app)/ # Protected application routes +│ │ ├── habits/ # Habit tracking feature +│ │ └── notes/ # Notes feature +│ └── login/ # Authentication pages +``` + +--- + +## Feature Documentation + +### Habit Tracking + +Track daily habits with a visual calendar interface that shows your progress over time. + +#### Capabilities + +- **Create habits** with custom names, targets, and optional units (minutes, reps, pages, etc.) +- **Track progress** with numeric values, not just checkboxes +- **Set duration** with optional start and end dates +- **Mark as inactive** to pause tracking without deleting history +- **Visual calendar** showing completion status across days + +#### Usage + +1. Click **"New Habit"** to create a habit +2. Set your daily target and optional unit +3. Use the calendar grid to log completions +4. Click cells to set values or mark as complete +5. Right-click cells for additional options (mark failed, clear) + +--- + +### Notes + +A markdown-based note-taking system with real-time sync, tagging, and powerful search. + +#### Capabilities + +- **Markdown editing** with live preview and syntax highlighting +- **Auto-save** with 500ms debounce after typing stops +- **Full-text search** across titles, content, and tags +- **Tag organization** with free-form user-created tags +- **Pin important notes** to keep them at the top +- **Archive notes** to hide without deleting +- **Trash with recovery** - deleted notes are retained for 30 days + +#### Workflow + +**Creating Notes:** +1. Click **"New Note"** button +2. Start typing - title is optional +3. Notes auto-save as you type + +**Organizing Notes:** +- Use the **tabs** to filter: All, Pinned, Archived, Trash +- Add **tags** via the note action menu +- **Pin** important notes to keep them visible +- **Archive** notes you want to keep but hide + +**Finding Notes:** +- Use the **search bar** to find notes by title, content, or tags +- Search is instant and filters the current view + +**Editor Features:** +- Switch between **Write** and **Preview** tabs +- Full **GitHub-flavored markdown** support +- **Syntax highlighting** for code blocks +- Character count displayed in footer + +--- + +## Security + +### Authentication + +Bullseye uses Better Auth for secure email/password authentication. Sessions are managed via HTTP-only cookies with automatic expiration. + +### Data Isolation + +All data is scoped to individual users via row-level security. Triplit enforces that users can only read and write their own data through permission filters on every collection. + +### Important: Shared Browser Warning + +**Triplit stores data locally in IndexedDB for offline support.** This means: + +- Data is cached in the browser's IndexedDB storage +- If multiple users share the same browser profile, **they may be able to access each other's cached data** +- This applies even after logging out, as IndexedDB persists until explicitly cleared + +**Recommendations for shared computers:** + +1. Use separate browser profiles for each user +2. Use private/incognito browsing mode +3. Clear browser data (specifically IndexedDB) after logging out +4. Consider this app unsuitable for highly sensitive data on shared devices + +--- \ No newline at end of file