https://github.com/kjanat/chatlogger-api-go
Go backend for the multi-tenant ChatLogger API.
https://github.com/kjanat/chatlogger-api-go
api automation chatlogger devops golang server
Last synced: 26 days ago
JSON representation
Go backend for the multi-tenant ChatLogger API.
- Host: GitHub
- URL: https://github.com/kjanat/chatlogger-api-go
- Owner: kjanat
- License: mit
- Created: 2025-04-20T20:28:56.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2025-07-06T20:07:51.000Z (7 months ago)
- Last Synced: 2025-07-06T20:19:07.836Z (7 months ago)
- Topics: api, automation, chatlogger, devops, golang, server
- Language: Go
- Homepage:
- Size: 684 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# ChatLogger API (Go)
[](go.mod)
[][Package documentation]
[][Go report]
[][API Docs]
[](https://github.com/kjanat/chatlogger-api-go/tags)
[][Latest release]
[](LICENSE)
[][Commits]
[][Commits]
[][Build]
[][Codecov]
[][Issues]
A multi-tenant backend API for logging and managing chat sessions, supporting both authenticated and unauthenticated usage with analytics capabilities.
## 🚀 Features
- **Multi-tenancy**: Separate organizations with isolated data
- **Dual Authentication**: API key for chat plugins and JWT for dashboard users
- **Role-based Access Control**: Superadmin, admin, user, and viewer roles with specific permissions
- **Analytics**: Usage metrics per organization with customizable reporting
- **Export Capabilities**: Export chat data in multiple formats (CSV, JSON) with both sync and async options
- **Clean Architecture**: Separation of concerns with layered design (handler → service → repository)
- **Strategy Pattern**: Used for exporter formats (JSON, CSV) and other pluggable components
- **Dependency Injection**: Constructor-based DI for improved testability and maintainability
- **Asynchronous Jobs**: Background processing with Redis and Asynq for resource-intensive tasks
## Documentation
The API is documented using Swagger/OpenAPI:
1. Generate documentation: `./scripts/docs_generate.sh` or `./scripts/docs_generate.ps1`
2. Start the server: `go run cmd/server/main.go`
3. Open browser: [`http://localhost:8080/openapi/index.html`](http://localhost:8080/openapi/index.html)
> [!TIP]
> View the package documentation for more details on the API endpoints and usage.
> [godoc.org][Package documentation]
> The API documentation is also available online at [chatlogger-api-docs.kjanat.com][API Docs].
## 🛠️ Tech Stack
- **Language**: [Go 1.24.2+](https://github.com/kjanat/chatlogger-api-go/blob/master/go.mod#L3)
- **Web Framework**: [Gin][Gin]
- **ORM**: [GORM][Gorm] with PostgreSQL
- **Authentication**: JWT using [golang-jwt/jwt][JWT]
- **Password Hashing**: bcrypt
- **Configuration**: Environment-based loading
- **Queue System**: [Asynq][Asynq] with Redis (for async exports)
- **Containerization**: Docker & Docker Compose
## 📋 Prerequisites
- Go 1.24.2 or higher
- PostgreSQL 14+
- Redis (optional, for async exports)
- Docker & Docker Compose (optional for containerized deployment)
## 🚀 Quick Start
### Running with Docker
The easiest way to get started is using Docker Compose:
```bash
# Clone the repository
git clone https://github.com/kjanat/chatlogger-api-go.git
cd chatlogger-api-go
# Start the application and database
docker-compose up -d
```
The API will be available at `http://localhost:8080`.
### Running Locally
```bash
# Clone the repository
git clone https://github.com/kjanat/chatlogger-api-go.git
cd chatlogger-api-go
# Install dependencies
go mod download
# Setup environment variables (copy example and modify)
cp .env.example .env
# Edit .env with your database credentials and settings
# Run migrations
psql -U postgres -d chatlogger -f migrations/001_initial_schema.sql
psql -U postgres -d chatlogger -f migrations/002_ensure_defaults.sql
psql -U postgres -d chatlogger -f migrations/003_add_exports_table.sql
# Run the server
go run cmd/server/main.go
# Run the worker (optional, for async exports)
go run cmd/worker/main.go
```
## 🔑 Authentication
### Chat Plugin (Public API)
Uses API key authentication via the `x-organization-api-key` header:
```bash
curl -X POST \
http://localhost:8080/v1/orgs/acme/chats \
-H 'x-organization-api-key: your-api-key' \
-H 'Content-Type: application/json' \
-d '{
"title": "Support Chat",
"tags": ["support", "billing"],
"metadata": {
"browser": "Chrome",
"platform": "Windows"
}
}'
```
### Dashboard (User Authentication)
Uses email/password login with JWT authentication:
```bash
# Login and get JWT cookie
curl -X POST \
http://localhost:8080/auth/login \
-H 'Content-Type: application/json' \
-d '{
"email": "admin@example.com",
"password": "your-password"
}' \
-c cookies.txt
# Use the JWT cookie for authenticated requests
curl -X GET \
http://localhost:8080/users/me \
-b cookies.txt
```
## 🔒 Role-Based Access Control
The API implements a comprehensive role-based access control system:
| Role | Description | Capabilities |
| :----------- | :------------------------------------------------- | :------------------------------------------------------- |
| `superadmin` | System-wide administrator with unrestricted access | Full access to all endpoints and organizations |
| `admin` | Organization administrator | Full access within their organization including API keys |
| `user` | Regular organization user | Access to own chats/messages and basic functionality |
| `viewer` | Read-only user | View-only access to permitted resources |
RBAC is implemented via middleware that checks the user's role before allowing access to protected resources.
## 📁 Project Structure
```plaintext
/cmd
/server → Main API server entry point
/tools → Utility tools
/worker → Background job worker for async exports
/internal
/api → Gin router and setup
/config → Configuration loading
/domain → Core models and interfaces
/handler → Request handlers
/hash → Password hashing utilities
/jobs → Queue and processor for async tasks
/middleware → Auth, RBAC, logging middleware
/repository → Database access layer
/service → Business logic layer
/strategy → Strategy pattern implementations (exporters)
/version → Version information
/migrations → SQL schema migrations
/scripts → Utility scripts
```
## 📊 API Endpoints
### System Endpoints
| Method | Endpoint | Description |
| :----- | :-------------- | :----------------------- |
| `GET` | `/health` | Health check endpoint |
| `GET` | `/version` | API version information |
| `GET` | `/openapi/*any` | Swagger UI documentation |
| `GET` | `/openapi/*any` | OpenAPI documentation |
### Auth Endpoints
| Method | Endpoint | Description |
| :----- | :--------------- | :-------------------------- |
| `POST` | `/auth/login` | Login and get JWT cookie |
| `POST` | `/auth/register` | Register a new user |
| `POST` | `/auth/logout` | Logout and clear JWT cookie |
### Dashboard API (Authenticated with JWT)
| Method | Endpoint | Description |
| :------- | :--------------------------- | :----------------------------- |
| `GET` | `/v1/users/me` | Get current user profile |
| `PATCH` | `/v1/users/me` | Update current user profile |
| `POST` | `/v1/users/me/password` | Change current user's password |
| `POST` | `/v1/chats` | Create a new chat |
| `GET` | `/v1/chats` | List user's chats |
| `GET` | `/v1/chats/:chatID` | Get a specific chat |
| `PATCH` | `/v1/chats/:chatID` | Update a chat |
| `DELETE` | `/v1/chats/:chatID` | Delete a chat |
| `GET` | `/v1/chats/:chatID/messages` | Get messages from a chat |
| `GET` | `/v1/analytics/messages` | Get message analytics |
### Admin-Only Endpoints (JWT + Admin Role)
| Method | Endpoint | Description |
| :------- | :------------------------ | :------------------------- |
| `GET` | `/v1/orgs/me/apikeys` | List organization API keys |
| `POST` | `/v1/orgs/me/apikeys` | Generate a new API key |
| `DELETE` | `/v1/orgs/me/apikeys/:id` | Revoke an API key |
### Export Endpoints (JWT Auth)
| Method | Endpoint | Description |
| :----- | :------------------------- | :------------------------ |
| `POST` | `/v1/exports` | Create async export job |
| `GET` | `/v1/exports` | List export jobs |
| `GET` | `/v1/exports/:id` | Get export job status |
| `GET` | `/v1/exports/:id/download` | Download completed export |
| `POST` | `/v1/exports/sync` | Create synchronous export |
### Public API (API Key Auth)
| Method | Endpoint | Description |
| :----- | :-------------------------------------- | :------------------------ |
| `POST` | `/v1/orgs/:slug/chats` | Create a new chat session |
| `POST` | `/v1/orgs/:slug/chats/:chatID/messages` | Add a message to a chat |
## 🔧 Configuration
The application is configured using environment variables:
| Variable | Description | Default |
| :------------- | :------------------------------ | :--------------- |
| `PORT` | Server port | `8080` |
| `DATABASE_URL` | PostgreSQL connection string | Required |
| `JWT_SECRET` | Secret for JWT signing | Required |
| `REDIS_ADDR` | Redis address for job queue | `localhost:6379` |
| `EXPORT_DIR` | Directory to store export files | `./exports` |
## ⚙️ Export System
The application supports both synchronous and asynchronous exports:
### Synchronous Exports
- Immediate response with download
- Good for small data sets
- Available at `/exports/orgs/me/sync`
- Works without Redis
### Asynchronous Exports
- Queued processing with status tracking
- Better for large data sets
- Requires Redis and worker process
- Creates a job at `/exports/orgs/me`
- Check status at `/exports/orgs/me/:id`
- Download at `/exports/orgs/me/:id/download`
Both export types support JSON and CSV formats.
## 🧪 Testing
```bash
# Run all tests
go test ./...
# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
# Run linting checks
golangci-lint run
```
## 🚢 Deployment
### Version Information
The application includes version information that can be injected during build:
```bash
# Build with version information
docker build -t chatlogger-api \
--build-arg VERSION=0.5.0 \
--build-arg BUILD_TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
--build-arg GIT_COMMIT=$(git rev-parse HEAD) \
.
```
### Image Verification
All container images are signed using [Sigstore cosign](https://github.com/sigstore/cosign). You can verify the authenticity of the images using the following command:
```bash
# Verify the container image signature
cosign verify \
--key=cosign.pub \
ghcr.io/kjanat/chatlogger-api-server:0.5.0
# Or use the public key URL
cosign verify \
--key=https://raw.githubusercontent.com/kjanat/chatlogger-api-go/master/cosign.pub \
ghcr.io/kjanat/chatlogger-api-worker:0.5.0
```
The public key for verification ([`cosign.pub`](cosign.pub)) is available in the root of the repository. For production deployments, we recommend verifying image signatures as part of your CI/CD pipeline to ensure supply chain security.
### CI/CD
The project includes GitHub Actions workflows for CI/CD:
- **Build Workflow**: Builds, tests, and tags versions on pushes to main
- **Release Workflow**: Creates GitHub releases when tags are pushed
## 📝 Next Steps and Enhancements
Here are some potential enhancements planned for future development:
- [x] **Export Features**: Implemented export functionality as a strategy pattern (JSON/CSV)
- [x] **Async Exports**: Added background processing for large exports
- [x] **Documentation**: Generated API documentation with Swagger/OpenAPI
- [ ] **Pagination**: Add cursor-based pagination to list endpoints
- [ ] **Enhanced Testing**: Expand unit and integration test coverage
- [ ] **Monitoring**: Add structured logging and metrics collection
- [ ] **Real-time notifications**: Add WebSocket support for live updates
- [ ] **Multi-factor Authentication**: Add 2FA support for dashboard users
- [ ] **Improved Analytics**: More detailed analytics dashboards and reports
- [ ] **Search Capabilities**: Add full-text search for chat messages
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
[Commits]: https://github.com/kjanat/chatlogger-api-go/commits/master/
[Latest release]: https://github.com/kjanat/chatlogger-api-go/releases/latest
[Issues]: https://github.com/kjanat/chatlogger-api-go/issues
[Go report]: https://goreportcard.com/report/github.com/kjanat/chatlogger-api-go
[Gin]: https://github.com/gin-gonic/gin
[Gorm]: https://gorm.io/
[JWT]: https://github.com/golang-jwt/jwt/tree/v5
[Asynq]: https://github.com/hibiken/asynq
[Codecov]: https://codecov.io/gh/kjanat/chatlogger-api-go
[Build]: https://github.com/kjanat/chatlogger-api-go/actions/workflows/chatlogger-pipeline.yml
[Package documentation]: https://godoc.org/github.com/kjanat/chatlogger-api-go
[API Docs]: https://chatlogger-api-docs.kjanat.com/