113 lines
3.6 KiB
Markdown
113 lines
3.6 KiB
Markdown
|
# Go Backend Control Plane
|
||
|
|
|
||
|
|
This is the Go backend for the enterprise document collaboration platform, serving as the single source of truth for authentication, organizations, permissions, sessions, and orchestration.
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
The backend is designed for security, scale, auditability, and SaaS readiness. It uses OIDC authentication via Nextcloud and enforces organization-scoped permissions.
|
||
|
|
|
||
|
|
### Core Principles
|
||
|
|
- **Single Source of Truth**: All auth, orgs, permissions, and sessions are managed here.
|
||
|
|
- **Untrusted Frontend**: The backend does not trust client-side permissions.
|
||
|
|
- **Organization Scoping**: Every API request is org-scoped.
|
||
|
|
- **Audit Logging**: All sensitive actions are logged.
|
||
|
|
|
||
|
|
### Key Components
|
||
|
|
- **Authentication**: OIDC via Nextcloud
|
||
|
|
- **Sessions**: Short-lived JWTs (5-15 minutes)
|
||
|
|
- **Organizations**: Multi-org support with role-based permissions
|
||
|
|
- **File Mediation**: Talks to Nextcloud via WebDAV/APIs, no direct client access
|
||
|
|
- **Document Sessions**: Generates signed URLs for viewers and editors (Collabora)
|
||
|
|
|
||
|
|
### Tech Stack
|
||
|
|
- **Language**: Go 1.22+
|
||
|
|
- **Framework**: Chi router
|
||
|
|
- **Database**: PostgreSQL 16
|
||
|
|
- **JWT**: golang-jwt/jwt/v4
|
||
|
|
- **Deployment**: Ready for containerization
|
||
|
|
|
||
|
|
## Project Structure
|
||
|
|
```
|
||
|
|
.
|
||
|
|
├── cmd/api/main.go # Application entry point
|
||
|
|
├── internal/
|
||
|
|
│ ├── auth/ # OIDC authentication logic
|
||
|
|
│ ├── session/ # Session management
|
||
|
|
│ ├── org/ # Organization resolution
|
||
|
|
│ ├── permission/ # Permission checking
|
||
|
|
│ ├── files/ # File access mediation
|
||
|
|
│ ├── documents/ # Document session generation
|
||
|
|
│ ├── collabora/ # Collabora editor integration
|
||
|
|
│ ├── audit/ # Audit logging
|
||
|
|
│ ├── middleware/ # HTTP middleware (auth, org, rate limit)
|
||
|
|
│ ├── config/ # Configuration loading
|
||
|
|
│ ├── database/ # DB connections and migrations
|
||
|
|
│ └── http/ # HTTP server and routes
|
||
|
|
├── pkg/jwt/ # JWT utilities
|
||
|
|
├── migrations/ # Database migrations
|
||
|
|
├── scripts/ # Utility scripts
|
||
|
|
├── .env.example # Environment variables template
|
||
|
|
├── Makefile # Build and deployment tasks
|
||
|
|
└── README.md
|
||
|
|
```
|
||
|
|
|
||
|
|
## Getting Started
|
||
|
|
|
||
|
|
1. **Initialize**:
|
||
|
|
```bash
|
||
|
|
go mod init go.b0esche.cloud/backend
|
||
|
|
go mod tidy
|
||
|
|
```
|
||
|
|
|
||
|
|
2. **Set up PostgreSQL**:
|
||
|
|
- Install PostgreSQL 16
|
||
|
|
- Create a database
|
||
|
|
- Run migrations:
|
||
|
|
```bash
|
||
|
|
psql -d your_database < migrations/0001_initial.sql
|
||
|
|
```
|
||
|
|
|
||
|
|
3. **Configure Environment**:
|
||
|
|
Copy `.env.example` to `.env` and fill in values, especially database URL and OIDC settings.
|
||
|
|
|
||
|
|
4. **Run**:
|
||
|
|
```bash
|
||
|
|
go run cmd/api/main.go
|
||
|
|
```
|
||
|
|
|
||
|
|
5. **Health Check**:
|
||
|
|
```bash
|
||
|
|
curl http://localhost:8080/health
|
||
|
|
```
|
||
|
|
|
||
|
|
## API Endpoints
|
||
|
|
|
||
|
|
- `GET /health` - Health check
|
||
|
|
- `GET /auth/login` - Initiate OIDC login (redirects to Nextcloud)
|
||
|
|
- `GET /auth/callback` - OIDC callback (returns JWT token)
|
||
|
|
|
||
|
|
## Development
|
||
|
|
|
||
|
|
- Use Go 1.22+
|
||
|
|
- Follow Go conventions
|
||
|
|
- Add tests for critical components
|
||
|
|
- Use structured logging
|
||
|
|
- No global mutable state
|
||
|
|
- No business logic in handlers
|
||
|
|
|
||
|
|
## Security
|
||
|
|
|
||
|
|
- All handlers must go through middleware chain
|
||
|
|
- JWTs are short-lived
|
||
|
|
- Permissions resolved server-side only
|
||
|
|
- Audit all sensitive actions
|
||
|
|
- Rate limiting implemented
|
||
|
|
- No direct DB access from handlers
|
||
|
|
|
||
|
|
## Roadmap
|
||
|
|
|
||
|
|
1. Complete OIDC implementation
|
||
|
|
2. Add database integration
|
||
|
|
3. Implement org and permission resolution
|
||
|
|
4. Add file access APIs
|
||
|
|
5. Integrate with Nextcloud and Collabora
|