b0esche_cloud/go_cloud

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:

   go mod init go.b0esche.cloud/backend
   go mod tidy
   

2. Set up PostgreSQL:

   • Install PostgreSQL 16
   • Create a database
   • Run migrations:

     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:

   go run cmd/api/main.go
   

5. Health Check:

   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