Knowledge Capsule is a fast, simple, Go-based backend that allows you to create, store, search, and organize “knowledge capsules” — bite-sized learning notes categorized by topics and tags. Perfect for personal knowledge bases, team learning platforms, or lightweight documentation systems.
- 🔐 User Authentication – Secure JWT-based login & registration
- 🧠 Capsule Management – Create, read, and organize knowledge entries
- 🗂️ Topic Organization – Categorize capsules using topics
- 🔍 Powerful Search – Search capsules by title or content
- 🏷️ Tagging System – Add tags for deeper filtering
- 💾 PostgreSQL + GORM – Persistent database storage
- 👤 RBAC – Roles: user, admin, superadmin (role assignment by admin/superadmin)
- 👥 User Management – Profile, avatar, list users (admin), admin team (superadmin)
- 🔍 Global Search – Admin-only search across users, topics, capsules
- 📋 Filtering – Query params on GET endpoints (topic, tags, q, is_private, role)
- 💬 Real-time Chat – Fully WebSocket-based (send messages, fetch history over socket)
- 📂 File Uploads – Upload and serve files locally
- 🏎️ Go (1.25+)
- 🐘 PostgreSQL – Database
- 📦 Docker & Docker Compose
- 🔁 Air (Live Reload)
- 🛠️ Makefile for workflow automation
- ⚙️ Lefthook for Git hooks
git clone https://github.com/shahadathhs/knowledge-capsule.git
cd knowledge-capsuleCopy .env.example to .env and fill in values:
cp .env.example .envRequired variables:
| Variable | Description |
|---|---|
PORT |
Server port (default: 8080) |
GO_ENV |
development or production |
JWT_SECRET |
Secret for JWT signing |
DATABASE_URL |
PostgreSQL connection string |
POSTGRES_USER |
DB user (for Docker Compose) |
POSTGRES_PASSWORD |
DB password |
POSTGRES_DB |
Database name |
SUPERADMIN_EMAIL |
(Optional) Superadmin email – creates/updates on startup |
SUPERADMIN_PASSWORD |
(Optional) Superadmin password |
SUPERADMIN_NAME |
(Optional) Superadmin display name |
💡 Generate JWT secret: make g-jwt
Docker Compose starts PostgreSQL + API together. The database is included in both dev and prod profiles.
make up-dev👉 API at http://localhost:8081 · PostgreSQL on localhost:5432
make up👉 API at http://localhost:8080 · PostgreSQL on localhost:5432
If you run the API locally (make run) and want PostgreSQL in Docker:
make db # Start PostgreSQL
make down-db # Stop PostgreSQLmake down-dev # dev
make down # prodEnsure PostgreSQL is running (e.g. make db or your own instance) and DATABASE_URL is set in .env.
Install dependencies:
make installStart server with live reload:
make runOr build & run binary:
make build-local
./tmp/serverGET /test-ws — WebSocket chat test page (same origin as API, no CORS issues)
Swagger UI at /docs/index.html
Protected endpoints: Click Authorize, enter Bearer <your-jwt-token> (get token from POST /api/auth/login), then Authorize again. All subsequent requests will include the token.
POST /api/auth/register
Body:
{
"name": "John Doe",
"email": "john@example.com",
"password": "securepassword"
}POST /api/auth/login
- 📥 GET
/api/users/me– Current user profile (id, name, email, role, avatar_url) - ✏️ PATCH
/api/users/me– Update name, avatar_url
- 📥 GET
/api/topics?page=1&limit=20&q=<search>– Fetch topics (paginated, filterable) - ➕ POST
/api/topics– Create topic - ✏️ PUT
/api/topics/{id}– Update topic - 🗑️ DELETE
/api/topics/{id}– Delete topic
POST /api/capsules
{
"title": "Interfaces in Go",
"content": "Interfaces are named collections of method signatures...",
"topic": "Golang",
"tags": ["programming", "go"],
"is_private": false
}GET /api/capsules?page=1&limit=20&topic=&tags=&q=&is_private= (all query params optional)
PUT /api/capsules/{id}
DELETE /api/capsules/{id}
GET endpoints support search + filter via query params (q, page, limit, etc.):
GET /api/capsules?q=&topic=&tags=&is_private=– Search/filter capsules (owner only)GET /api/topics?q=– Search/filter topicsGET /api/users?q=&role=– Search/filter users (admin only)
GET /api/admin/search?q=<query>&limit=10 – Global search (admin only): searches users, topics, and capsules in one request
- 📥 GET
/api/users– List users (admin, paginated:q,role,page,limit) - 📥 GET
/api/users/{id}– Get user by ID (admin) - 📥 GET
/api/admin/admins– List admins (superadmin only) - ✏️ POST
/api/admin/users/{id}/role– Set user role (superadmin only):{"role":"user|admin|superadmin"}
GET /health
✔ Confirms server is alive
GET /ws/chat — Connect with ?token=<jwt>
- Send message:
{ "type": "send", "payload": { "receiver_id": "...", "content": "...", "type": "text" } } - Get history:
{ "type": "get_history", "payload": { "user_id": "...", "page": 1, "limit": 20 } } - Server responses:
{ "type": "message"|"history"|"error", "payload": {...} }
POST /api/upload
- Body:
multipart/form-datawithfilefield.
GET /uploads/:filename
knowledge-capsule/
├── app/
│ ├── handlers/ # HTTP handlers
│ ├── middleware/ # Auth, logger, etc.
│ ├── models/ # Data models
│ └── store/ # GORM stores
├── pkg/
│ ├── config/ # Configuration loading
│ ├── db/ # PostgreSQL connection
│ └── utils/ # Helpers
├── web/ # Frontend assets (Chat UI)
├── docs/ # Swagger API docs
├── uploads/ # Uploaded files
├── scripts/ # Helper scripts
├── Dockerfile
├── Dockerfile.dev
├── compose.yaml
├── Makefile
└── main.go
- 📘
make help– See all commands ▶️ make run– Run locally with live reload- 🔨
make build-local– Build binary - 🐘
make db– Start PostgreSQL (for local dev) - ✨
make fmt– Format code - 🔍
make vet– Static analysis - 🧹
make tidy– Cleanup modules - 📝
make swagger– Generate API docs - 🔐
make g-jwt– Generate JWT secret