notely/README.md

Notely

Notely is a multi-space note application built with Go, Vue 3, MongoDB, and Redis.

The repository contains a Go backend, a Vue frontend, Docker Compose assets for local deployment, and Kubernetes manifests for cluster deployment. In containerized environments, the frontend is built into the backend image and served by the Go server. Docker Compose also places Nginx in front of the app for HTTP and HTTPS entry points.

What Is In This Repo

• Backend API in backend/
• Frontend SPA in frontend/
• Docker and Nginx assets in devops/docker/
• Kubernetes manifests in devops/kubernetes/
• Root documentation in README.md, QUICKSTART.md, ENV_SETUP.md, and PERMISSIONS.md

Core Features

• Email/password authentication
• Session cookies backed by Redis, with bearer-token fallback for API clients
• Admin bootstrap from environment variables
• Permission-based authorization with wildcard support
• Spaces, categories, and notes
• Full-text note search
• Public spaces and public notes
• Password-protected notes
• OAuth/OIDC provider support
• Feature flags for registration, provider login, public sharing, and file explorer support
• Optional S3-compatible file explorer when enabled through feature flags

Architecture Overview

Backend

• Language: Go
• Module: gitea.hostxtra.co.uk/mrhid6/notely/backend
• Entry point: backend/cmd/server/main.go
• Architecture style: domain/application/infrastructure/interfaces split
• Storage: MongoDB
• Session store: Redis

Frontend

• Framework: Vue 3
• Router: Vue Router
• State: Pinia
• Build tool: Vite

Container Layout

• devops/docker/Dockerfile builds the frontend and backend into a single app image
• docker-compose.yml starts:
  • mongodb
  • redis
  • notely (combined app image)
  • nginx

Documentation Map

• README.md: project overview and current architecture
• QUICKSTART.md: fast setup and day-to-day development commands
• ENV_SETUP.md: environment-variable reference and configuration layout
• PERMISSIONS.md: enforced permission model and naming

Getting Started

Docker Compose

1. Copy the root environment file:

cp .env.example .env

2. Start the stack:

docker compose up -d --build

3. Open the app:

• UI through Nginx: http://localhost
• Backend health check: http://localhost:8080/health
• MongoDB: localhost:27017
• Redis: localhost:6379

Local Development

Prerequisites:

• Go 1.25+
• Node.js 18+
• MongoDB
• Redis

Backend:

cd backend
cp .env.example .env
go mod download
go run ./cmd/server/main.go

Frontend:

cd frontend
cp .env.example .env
npm install
npm run dev

Local frontend development runs at http://localhost:5173 and proxies /api requests to http://localhost:8080.

API Surface

The router in backend/cmd/server/main.go currently exposes these endpoint groups.

Public Endpoints

• GET /health
• POST /api/v1/auth/register
• POST /api/v1/auth/login
• POST /api/v1/auth/refresh
• POST /api/v1/auth/logout
• GET /api/v1/auth/providers
• GET /api/v1/auth/providers/{providerId}/start
• GET /api/v1/auth/providers/{providerId}/callback
• GET /api/v1/settings/feature-flags
• GET /api/v1/public/spaces
• GET /api/v1/public/spaces/{spaceId}
• GET /api/v1/public/spaces/{spaceId}/notes
• GET /api/v1/public/spaces/{spaceId}/notes/{noteId}
• POST /api/v1/public/spaces/{spaceId}/notes/{noteId}/unlock

Authenticated User Endpoints

• GET /api/v1/auth/me
• Space CRUD under /api/v1/spaces
• Space member management under /api/v1/spaces/{spaceId}/members
• Note CRUD, search, and unlock under /api/v1/spaces/{spaceId}/notes
• Category CRUD and move under /api/v1/spaces/{spaceId}/categories
• File explorer operations under /api/v1/spaces/{spaceId}/files

Admin Endpoints

Admin routes live under /api/v1/admin and cover:

• users
• groups
• spaces
• feature flags
• auth providers

Permissions

Notely uses permission-based authorization, not fixed owner/editor/viewer roles.

• Global permissions include space.create, space.edit, and space.delete
• Space-scoped permissions follow space.<space_key>.<action>
• Example: space.product_docs.note.create
• Example: space.product_docs.settings.delete
• Space deletion requires either:
  • global space.delete, or
  • space-scoped space.<space_key>.settings.delete

See PERMISSIONS.md for the current enforced permission set.

Testing And Quality Checks

Backend:

cd backend
go test ./...
go test -v ./tests/unit/...
go test -v ./tests/integration/...

Frontend:

cd frontend
npm run build
npm run lint
npm run test

Deployment Notes

Docker Compose

Docker Compose uses the combined application image plus Nginx, MongoDB, and Redis. Configuration is driven by the root .env file.

Kubernetes

The manifest at devops/kubernetes/deployment.yaml currently provisions:

• noteapp namespace
• MongoDB StatefulSet and PVC
• single noteapp Deployment for the combined app image
• ClusterIP services
• Ingress
• HorizontalPodAutoscaler

Apply it with:

kubectl apply -f devops/kubernetes/deployment.yaml

Current Repo Layout

noteapp/
├── backend/
│   ├── cmd/server/
│   ├── internal/
│   ├── pkg/
│   ├── tests/
│   └── .env.example
├── frontend/
│   ├── src/
│   ├── tests/
│   ├── package.json
│   ├── vite.config.js
│   ├── vitest.config.js
│   └── .env.example
├── devops/
│   ├── docker/
│   │   ├── Dockerfile
│   │   ├── nginx.conf
│   │   └── ssl/
│   └── kubernetes/
│       └── deployment.yaml
├── docker-compose.yml
├── .env.example
├── ENV_SETUP.md
├── PERMISSIONS.md
├── QUICKSTART.md
└── README.md

Notes For Contributors

• Check PERMISSIONS.md when changing authorization behavior
• Check ENV_SETUP.md when adding or changing configuration
• Check backend/cmd/server/main.go before documenting routes
• Keep docs aligned with actual package scripts and checked-in files