Initial commit: Open sourcing all of the Maple Open Technologies code.

cloud/maplefile-backend/internal/interface/http/README.md

@@ -0,0 +1,122 @@
+# MapleFile HTTP Server
+
+Standalone HTTP server for MapleFile backend - completely independent with no Manifold orchestration.
+
+## Architecture
+
+- **Standard Library**: Uses `net/http` with Go 1.22+ routing patterns
+- **No Orchestration**: Direct route registration (no `AsRoute()` wrappers)
+- **Middleware Stack**: Applied globally with per-route authentication
+- **Lifecycle Management**: Integrated with Uber FX for graceful shutdown
+
+## Server Configuration
+
+Configured via environment variables in `.env`:
+
+```env
+SERVER_HOST=0.0.0.0
+SERVER_PORT=8000
+SERVER_READ_TIMEOUT=30s
+SERVER_WRITE_TIMEOUT=30s
+SERVER_IDLE_TIMEOUT=60s
+SERVER_SHUTDOWN_TIMEOUT=10s
+```
+
+## Middleware Stack
+
+Applied in this order (outermost to innermost):
+
+1. **Recovery** - Catches panics and returns 500
+2. **Logging** - Logs all requests with duration
+3. **CORS** - Handles cross-origin requests
+4. **Authentication** (per-route) - JWT validation for protected routes
+
+## Route Structure
+
+### Public Routes
+- `GET /health` - Health check
+- `GET /version` - Version info
+- `POST /api/v1/auth/register` - Registration
+- `POST /api/v1/auth/login` - Login
+
+### Protected Routes
+All `/api/v1/*` routes (except auth) require JWT authentication via:
+```
+Authorization: Bearer <jwt_token>
+```
+
+Key protected endpoints include:
+- `GET/PUT/DELETE /api/v1/me` - User profile management
+- `POST/GET/PUT/DELETE /api/v1/collections/*` - Collection CRUD
+- `POST/GET/PUT/DELETE /api/v1/file/*` - File operations
+- `POST /api/v1/invites/send-email` - Send invitation to non-registered user
+
+See `routes.go` for complete endpoint list.
+
+## Handler Registration
+
+Routes are registered in `server.go` -> `registerRoutes()`:
+
+```go
+// Public route
+s.mux.HandleFunc("GET /health", s.healthCheckHandler)
+
+// Protected route
+s.mux.HandleFunc("POST /api/v1/collections",
+    s.middleware.Attach(s.handlers.CreateCollection))
+```
+
+## Starting the Server
+
+The server is started automatically by Uber FX:
+
+```go
+fx.New(
+    fx.Provide(http.NewServer),  // Creates and starts server
+    // ... other providers
+)
+```
+
+Lifecycle hooks handle:
+- **OnStart**: Starts HTTP listener in goroutine
+- **OnStop**: Graceful shutdown with timeout
+
+## Response Format
+
+All JSON responses follow this structure:
+
+**Success:**
+```json
+{
+  "data": { ... },
+  "message": "Success"
+}
+```
+
+**Error:**
+```json
+{
+  "error": "Error message",
+  "code": "ERROR_CODE"
+}
+```
+
+## Health Checks
+
+```bash
+# Basic health check
+curl http://localhost:8000/health
+
+# Version check
+curl http://localhost:8000/version
+```
+
+## Development
+
+Build and run:
+```bash
+task build
+./maplefile-backend daemon
+```
+
+The server will start on `http://localhost:8000` by default.