250 lines
6.1 KiB
Markdown
250 lines
6.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
2. Start the stack:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cd backend
|
|
cp .env.example .env
|
|
go mod download
|
|
go run ./cmd/server/main.go
|
|
```
|
|
|
|
Frontend:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
cd backend
|
|
go test ./...
|
|
go test -v ./tests/unit/...
|
|
go test -v ./tests/integration/...
|
|
```
|
|
|
|
Frontend:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
kubectl apply -f devops/kubernetes/deployment.yaml
|
|
```
|
|
|
|
## Current Repo Layout
|
|
|
|
```text
|
|
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
|