A modern, lightweight, privacy-focused note-taking web application with Backblaze B2 S3 image attachments and MySQL database storage.
Key Features • Architecture • Quick Start • Configuration • API Reference • Contributing • License
Notes Web App is an open-source, nimble note-taking platform designed for speed, clarity, and control. It brings together a responsive, glassmorphic UI aesthetic inspired by modern developer tooling, a high-performance Fastify TypeScript backend, a lightweight MySQL database driven by Drizzle ORM, and cloud image storage via Backblaze B2 (S3-compatible API).
Whether organizing code snippets, drafting technical documents, or managing project notes with inline visual attachments, Notes Web App provides an uncluttered workspace in both Light and Dark modes.
- Tailored Aesthetics: Built with the
Outfittypography, sleek frosted glass headers (glass-panel), crisp dark/light themes, and custom scrollbars. - Responsive Layout: Adaptive sidebar for instant filtering by tags, pinned notes, archives, and image gallery.
- Instant Command Palette (
⌘K/Ctrl+K): Quickly search notes, switch views, or toggle themes with keyboard navigation.
- Dual Mode Editor: Live split markdown editor with real-time preview and instant syntax highlighting.
- Formatting Toolbar: Fast actions for bold, italic, headings, blockquotes, code blocks, unordered/ordered lists, and check lists.
- Auto-Save & Status Indicators: Visual save indicators so work is never lost.
- Drag-and-Drop & Clipboard Paste: Paste screenshots directly into notes (
⌘V) or drop images into the editor. - Direct Cloud Storage: Uploads securely to Backblaze B2 via standard AWS S3 SDK v3 protocol with presigned upload URLs or Fastify streaming.
- Attachment Drawer & Inspector Modal: Full-resolution image zoom, copyable image markdown links, file size badges, and deletion controls.
- Media Gallery View: Browse all attached assets across your notebook in one consolidated view.
- Lightweight Schema: Zero bloat, blazing queries with Drizzle ORM and
mysql2. - Tagging & Categorization: Multi-tag support with color badges for quick categorization.
- Search & Pinning: Full-text instant filtering across note titles, contents, and tag labels.
┌─────────────────────────────────────────────────────────┐
│ Frontend (Vite + React + TS) │
│ - Outfit Font + Tailwind Glassmorphic Design System │
│ - Markdown Editor + Drag & Drop S3 Image Attachments │
│ - Command Palette (⌘K), Sidebar Filter, Inspector Modal│
└────────────────────────────┬────────────────────────────┘
│ REST API / JSON
┌────────────────────────────▼────────────────────────────┐
│ Backend (Fastify + TS) │
│ - RESTful Routes: Notes, Tags, S3 Attachments, Search │
│ - S3 / Backblaze Client (@aws-sdk/client-s3) │
│ - Drizzle ORM + Connection Pooling │
└──────────────┬────────────────────────────┬─────────────┘
│ │
▼ ▼
┌──────────────────────────────┐ ┌────────────────────────┐
│ MySQL Database │ │ Backblaze B2 Cloud S3 │
│ (Notes, Tags, Attachments) │ │ (Images / Media Assets)
└──────────────────────────────┘ └────────────────────────┘
- Node.js: v18.0.0 or higher
- MySQL: Server 8.0+ or MariaDB
- Backblaze B2 Account: S3-compatible Application Key ID, Secret Key, and Bucket name.
git clone https://github.com/yourusername/notes-web-app.git
cd notes-web-app
npm installCopy .env.example in backend/:
cp backend/.env.example backend/.envUpdate your database credentials and Backblaze B2 S3 credentials in backend/.env.
npm run dev:backend(The backend automatically creates missing tables on initial boot if not present).
# Starts both Backend (port 9548) and Frontend (port 9547)
npm run devVisit http://localhost:9547 to access the application.
| Variable | Required | Default | Description |
|---|---|---|---|
PORT |
No | 9548 |
Fastify server listen port |
HOST |
No | 0.0.0.0 |
Fastify host bind address |
CORS_ORIGIN |
No | http://localhost:9547 |
Allowed CORS frontend origin |
DB_HOST |
Yes | localhost |
MySQL Host |
DB_PORT |
No | 3306 |
MySQL Port |
DB_USER |
Yes | root |
MySQL User |
DB_PASSWORD |
Yes | "" |
MySQL Password |
DB_NAME |
Yes | notes_db |
MySQL Database Name |
S3_ENDPOINT |
Yes | - | Backblaze B2 Endpoint (e.g., https://s3.us-west-004.backblazeb2.com) |
S3_REGION |
Yes | us-west-004 |
S3 Region |
S3_BUCKET |
Yes | - | Backblaze B2 Bucket Name |
S3_ACCESS_KEY_ID |
Yes | - | Backblaze B2 Application Key ID |
S3_SECRET_ACCESS_KEY |
Yes | - | Backblaze B2 Application Key (Secret) |
S3_PUBLIC_BASE_URL |
No | - | Optional custom CDN / Public bucket base URL |
GET /api/notes- List all active notes (supports query filterssearch,tag,isPinned,isArchived).GET /api/notes/:id- Fetch single note with attachments and tags.POST /api/notes- Create a new note.PUT /api/notes/:id- Update note content, title, pin status, or archive status.DELETE /api/notes/:id- Permanently delete a note and its attached S3 objects.
POST /api/attachments/upload- Direct multipart image upload to Backblaze B2 S3.POST /api/attachments/presign- Request S3 presigned PUT URL for direct client upload.DELETE /api/attachments/:id- Delete an attachment from DB and Backblaze B2 bucket.
GET /api/health- Server, MySQL connection, and Backblaze S3 health status.GET /api/stats- Notebook statistics (total notes, attachments, tags, storage used).
Contributions are warmly welcomed! Please read our CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting Pull Requests.
This project is licensed under the MIT License.