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

Copy the root environment file:

cp .env.example .env

Start the stack:

docker compose up -d --build

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