ZettelMaster

A powerful note-taking and knowledge management application built with React, Express, TypeScript, and PocketBase.

🚀 Quick Start with Docker

Application URL: http://localhost:54657 PocketBase Admin: http://localhost:54658/_/

# Start the application
docker compose up -d --build

# Stop the application
docker compose down

# View logs
docker compose logs -f

See DOCKER-QUICK-START.md for a complete quick start guide. See DOCKER-SETUP.md for detailed Docker configuration and troubleshooting.

Port Assignments

Following the project's port assignment protocol (random ports 50000-60000):

Service	Port	Purpose
Main Application	54657	Web interface and API endpoints
PocketBase Admin	54658	Database administration interface

📖 About

ZettelMaster is a modern implementation of the Zettelkasten method for personal knowledge management. It allows you to:

• Create and organize notes with connections
• Link related ideas together
• Search and explore your knowledge graph
• Markdown support for rich text formatting
• Built-in database with PocketBase

🏗️ Technology Stack

Frontend

• React 18 - UI framework
• TypeScript - Type safety
• Vite - Build tool and dev server
• Wouter - Lightweight routing
• TanStack Query - Data fetching and caching
• shadcn/ui - Component library (Radix UI + Tailwind)
• Tailwind CSS - Styling

Backend

• Node.js 20 - Runtime
• Express - Web framework
• TypeScript - Type safety
• PocketBase - Embedded database and admin UI
• esbuild - Fast bundler

Infrastructure

• Docker - Containerization
• Docker Compose - Multi-container orchestration

📋 Prerequisites

For Docker (Recommended)

• Docker 20.10+
• Docker Compose 2.0+

For Local Development

• Node.js 20+
• npm or yarn
• PocketBase binary (auto-installed with Docker)

🚀 Getting Started

Option 1: Docker (Recommended)

1. Clone the repository

   git clone <repository-url>
   cd ZettelMaster
   

2. Start with Docker Compose

   docker compose up -d --build
   

3. Access the application

   • Application: http://localhost:54657
   • PocketBase Admin: http://localhost:54658/_/

4. Change default admin password

   • Login to PocketBase: admin@example.com / password123
   • Change password immediately for security

Option 2: Local Development

1. Install dependencies

   npm install
   

2. Start PocketBase

   ./scripts/start-pocketbase.sh
   

3. Start development server

   npm run dev
   

4. Access the application

   • Application: http://localhost:5000
   • PocketBase Admin: http://localhost:8090/_/

📜 Available Scripts

Script	Description
npm run dev	Start development server with hot reload
npm run build	Build for production (client + server)
npm start	Start production server
npm run check	TypeScript type checking
npm run db:push	Push database schema changes

🐳 Docker Commands

Command	Description
docker compose up -d	Start services in background
docker compose down	Stop all services
docker compose logs -f	View live logs
docker compose restart	Restart services
docker compose ps	Check service status
docker compose build	Rebuild Docker image

📁 Project Structure

ZettelMaster/
├── client/              # React frontend
│   ├── src/
│   │   ├── components/  # UI components
│   │   ├── hooks/       # React hooks
│   │   ├── lib/         # Utility functions
│   │   └── pages/       # Page components
│   └── index.html
├── server/              # Express backend
│   ├── index.ts         # Server entry point
│   ├── routes.ts        # API routes
│   ├── storage.ts       # Storage interface
│   ├── pocketbase-storage.ts  # PocketBase implementation
│   └── vite.ts          # Vite integration
├── shared/              # Shared code
│   └── schema.ts        # Data types and schemas
├── scripts/             # Utility scripts
│   ├── start-pocketbase.sh
│   └── init-pocketbase.js
├── docker/              # Docker configurations
│   ├── dev-deploy/
│   ├── test-deploy/
│   └── prod-deploy/
├── docs/                # Documentation
├── Dockerfile           # Docker image definition
├── docker-compose.yml   # Docker Compose configuration
└── package.json         # Dependencies and scripts

🔧 Configuration

Environment Variables

Create a .env file in the root directory:

NODE_ENV=production
PORT=5000
POCKETBASE_URL=http://localhost:8090

Docker Environment

Edit docker-compose.yml to customize:

• Port mappings
• Environment variables
• Resource limits
• Volume configurations

📊 Features

• Note Management: Create, edit, delete notes with markdown
• Connections: Link notes together to build knowledge graphs
• Search: Fast full-text search across all notes
• Tags: Organize notes with tags
• User Authentication: Secure user accounts with PocketBase
• Responsive Design: Works on desktop and mobile
• Real-time Updates: Live updates using React Query

🔒 Security

• PocketBase authentication and authorization
• Secure session management
• Password hashing
• HTTPS ready for production
• Environment-based configuration

📚 Documentation

• DOCKER-SETUP.md - Comprehensive Docker setup guide
• DOCKER-QUICK-START.md - Quick Docker reference
• POCKETBASE.md - PocketBase configuration
• ROADMAP.md - Project roadmap and features
• docs/ - Additional documentation

🤝 Development Workflow

Using Spec-Kit

This project uses Spec-Kit for spec-driven development:

# Establish project principles
/speckit.constitution

# Create baseline specification
/speckit.specify

# Create implementation plan
/speckit.plan

# Generate actionable tasks
/speckit.tasks

# Execute implementation
/speckit.implement

AI-Assisted Development

This project follows the AI-Chats protocol v3.2 for documenting AI-assisted development sessions.

Session documentation: ai-chats/

🐛 Troubleshooting

Docker Issues

• Port conflicts: Change ports in docker-compose.yml
• Container won't start: Check logs with docker compose logs
• Build failures: Try docker compose build --no-cache

Application Issues

• PocketBase not connecting: Verify PocketBase is running on port 8090
• Frontend not loading: Check that build completed successfully
• API errors: Check server logs for error messages

See DOCKER-SETUP.md for detailed troubleshooting.

🚀 Deployment

The application is production-ready with Docker. For deployment:

1. Update environment variables for production
2. Configure reverse proxy (nginx/traefik)
3. Enable HTTPS with SSL certificates
4. Set up regular backups of PocketBase data
5. Configure monitoring and logging

📄 License

MIT License

🙏 Acknowledgments

• Built with shadcn/ui
• Powered by PocketBase
• Icons from Lucide

---

Version: 1.0.0 Last Updated: 2025-10-28 Docker Support: ✅ Fully Supported