# 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