LeafLock

Important

THIS PROJECT IS A PRODUCT OF VIBE CODING AND TESTING AI/LLMS.

Badges

LeafLock is a privacy-first notes application with end-to-end encryption, real-time collaboration, and a Go backend. Everything can be self-hosted and kept under your control.

Features

• Modern Authentication: Pure Clerk authentication with social logins, MFA, and enterprise features
• End-to-end encryption handled on the client
• Zero-knowledge architecture for the backend
• Real-time collaboration with WebSockets
• Rich text editor with Markdown and code blocks
• Offline support with automatic sync when connectivity returns

Requirements

• Docker or Podman with Compose support
• Linux, macOS, or Windows with WSL2
• At least 2GB RAM (4GB recommended)
• Go toolchain (if you develop the backend)
• Node.js 18+ and pnpm 10 (if you develop the frontend)

Getting Started

1. Clone the repository:

   git clone https://github.com/RelativeSure/LeafLock.git
   cd LeafLock

2. (Optional) Override defaults:

   cp .env.example .env
   # tweak anything you want and docker compose will pick it up automatically

3. Start the full stack:

   docker compose up --build

   • Frontend UI: http://localhost:3000
   • Backend API: http://localhost:8080
   • API health check: http://localhost:8080/api/v1/health
   • Built assets are rebuilt automatically each time you rerun with --build

4. Stop everything when finished:

   docker compose down

5. Set up Clerk Authentication:

   • Get your Clerk keys from Clerk Dashboard
   • Add to your .env file:

     VITE_CLERK_PUBLISHABLE_KEY=pk_test_your_key_here
     CLERK_PUBLISHABLE_KEY=pk_test_your_key_here  
     CLERK_SECRET_KEY=sk_test_your_key_here

   • Visit /login to access Clerk's authentication components
   • Create your first account or sign in

   Note: Clerk handles all authentication - no default admin account is created.

Project Structure

• backend/: Go service, tests, and supporting Make targets
• frontend/: Vite + React app managed with pnpm
• docs/: User and operator documentation
• helm/: Helm charts for Kubernetes deployments
• scripts/: Local tooling, including git hook setup

Development

Backend (Go)

• Format and lint: make -C backend fmt and make -C backend vet
• Run tests: make -C backend test
• Coverage check: make -C backend test-coverage-check

Frontend (React + Vite)

1. Install dependencies with pnpm:

   cd frontend
   corepack use pnpm@10
   pnpm install

2. Start the dev server:

   pnpm dev

3. Run the test suite:

   pnpm test

Return to the repository root before using make targets again: cd ...

Tooling

• Install git hooks once per machine: pre-commit install
• Build container images locally: make build

Deployment

• Run docker compose up --build (or make up) for local deployments
• Helm charts under helm/ support Kubernetes clusters

Documentation

• docs/ADMIN.md: operational guide for provisioning, upgrades, and backups
• docs/admin-panel.md: UI walkthrough for administrators
• docs/rbac.md and docs/rate-limiting.md: security controls and traffic management
• docs/swagger.md: OpenAPI generation and API reference pointers
• docs/SCRIPTS.md: utility scripts used by automation and CI tasks

Troubleshooting

• Inspect logs for all services: make logs
• Check backend health: curl http://localhost:8080/api/v1/health
• Recreate containers if needed: run make down followed by docker compose build --no-cache or podman compose build --no-cache

Contributing

We welcome contributions of any size. Review CONTRIBUTING.md and run the provided checks before opening a pull request. Discussions and issues are tracked in GitHub.

License

LeafLock is released under the PolyForm Noncommercial License 1.0.0. See LICENSE for details.