create documentation
This commit is contained in:
@@ -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
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user