boc/landvex-admin/README.md

# LandveX Enterprise Platform - Admin Backend

Complete admin backend design for LandveX Enterprise Platform serving municipalities (kommuner) and enterprises.

## Architecture Overview

```
┌─────────────────────────────────────────────────────────┐
│                    React 19 Frontend                     │
│              (Admin Dashboard UI)                        │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│              FastAPI Backend (Python)                    │
│  Auth · Tenants · Users · Billing · Audit · Reports     │
└─────────────────────────────────────────────────────────┘
                           │
           ┌───────────────┼───────────────┐
           ▼               ▼               ▼
    ┌──────────┐   ┌──────────┐   ┌──────────┐
    │PostgreSQL│   │  Redis   │   │  Stripe  │
    │  (Data)  │   │ (Cache)  │   │(Payments)│
    └──────────┘   └──────────┘   └──────────┘
```

## Features

### 1. Customer Management (Tenants)
- Multi-tenant architecture with complete isolation
- Support for municipalities (kommuner) and enterprises
- Organization profiles with org numbers
- Tenant-specific settings and configurations

### 2. User Management with Roles
- RBAC (Role-Based Access Control) system
- Predefined roles: Superadmin, Admin, Editor, Viewer, API
- Custom role creation with granular permissions
- User invitation and activation workflow
- Account locking after failed login attempts
- MFA (Multi-Factor Authentication) support

### 3. Tenant Isolation
- Row-Level Security (RLS) in PostgreSQL
- Tenant resolution via JWT claims or API keys
- Automatic query filtering by tenant_id
- Separate data contexts per tenant

### 4. Audit Logging
- Comprehensive action logging
- User activity tracking
- Resource change history
- IP address and user agent capture
- Severity levels (info, warning, critical)
- Export capabilities (CSV/JSON)

### 5. API Key Management
- Secure key generation with prefix identification
- Scope-based permissions per key
- Rate limiting per key
- Key expiration and revocation
- Usage tracking

### 6. Billing & Subscriptions
- Subscription plan management
- Stripe integration for payments
- Invoice generation and PDF export
- Payment method management
- MRR and revenue tracking

### 7. Reports & Analytics
- Custom report builder
- Scheduled report generation
- Multiple output formats (PDF, CSV, JSON)
- Dashboard with KPI widgets
- API usage analytics

### 8. Plugin Management
- Plugin marketplace
- Tenant-specific plugin installation
- Plugin configuration per tenant
- System vs optional plugins
- Version management

## Project Structure

```
landvex-admin/
├── design.md                 # Complete design document
├── docker-compose.yml        # Local development stack
├── api/
│   └── openapi.yaml         # OpenAPI 3.1 specification
├── backend/
│   ├── app/
│   │   ├── main.py          # FastAPI entry point
│   │   ├── config.py        # Configuration
│   │   ├── database.py      # DB connection
│   │   ├── models/          # SQLAlchemy models
│   │   │   ├── tenant.py
│   │   │   ├── user.py
│   │   │   ├── billing.py
│   │   │   ├── api_key.py
│   │   │   ├── audit.py
│   │   │   ├── report.py
│   │   │   └── plugin.py
│   │   ├── api/             # API routes
│   │   │   ├── deps.py      # Dependencies
│   │   │   └── v1/
│   │   │       ├── auth.py
│   │   │       ├── tenants.py
│   │   │       ├── users.py
│   │   │       ├── roles.py
│   │   │       ├── api_keys.py
│   │   │       ├── billing.py
│   │   │       ├── audit.py
│   │   │       ├── reports.py
│   │   │       ├── plugins.py
│   │   │       └── dashboard.py
│   │   ├── core/            # Security & utilities
│   │   │   ├── security.py  # Password, JWT, API keys
│   │   │   ├── permissions.py # RBAC
│   │   │   └── exceptions.py
│   │   └── services/        # Business logic
│   ├── Dockerfile
│   └── requirements.txt
└── frontend/
    ├── src/
    │   ├── App.tsx
    │   ├── components/
    │   │   └── layout/
    │   │       ├── Layout.tsx
    │   │       ├── Sidebar.tsx
    │   │       └── TopBar.tsx
    │   ├── pages/
    │   │   ├── Dashboard.tsx
    │   │   ├── Tenants/
    │   │   ├── Users/
    │   │   ├── Roles/
    │   │   ├── Billing/
    │   │   ├── AuditLogs/
    │   │   ├── Reports/
    │   │   └── Plugins/
    │   ├── hooks/
    │   │   ├── useAuth.ts
    │   │   └── usePermissions.ts
    │   ├── stores/
    │   │   └── authStore.ts
    │   └── lib/
    │       └── api.ts
    ├── Dockerfile
    └── package.json
```

## Quick Start

### Prerequisites
- Docker & Docker Compose
- Node.js 20+ (for local frontend dev)
- Python 3.11+ (for local backend dev)

### Local Development

```bash
# Start all services
docker-compose up -d

# Backend API: http://localhost:8000
# Frontend: http://localhost:5173
# API Docs: http://localhost:8000/docs
```

### Environment Variables

```bash
# Backend
DATABASE_URL=postgresql+asyncpg://landvex:password@db:5432/landvex_admin
REDIS_URL=redis://redis:6379/0
SECRET_KEY=your-secret-key
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Frontend
VITE_API_URL=http://localhost:8000/api/v1
```

## Security Features

- **Authentication**: JWT tokens with refresh token rotation
- **Password Hashing**: Argon2id
- **API Keys**: SHA-256 hashed with prefix identification
- **Authorization**: RBAC with wildcard permissions
- **Tenant Isolation**: Row-Level Security in PostgreSQL
- **Audit Logging**: All state-changing operations logged
- **Rate Limiting**: Per-key and per-user limits
- **CORS**: Configurable allowed origins
- **Security Headers**: HSTS, CSP, X-Frame-Options, etc.

## API Endpoints

| Category | Endpoints |
|----------|-----------|
| Auth | `POST /auth/login`, `POST /auth/refresh`, `POST /auth/mfa/verify` |
| Tenants | `GET /tenants`, `POST /tenants`, `GET /tenants/{id}` |
| Users | `GET /users`, `POST /users`, `PATCH /users/{id}` |
| Roles | `GET /roles`, `POST /roles`, `PATCH /roles/{id}` |
| API Keys | `GET /api-keys`, `POST /api-keys`, `POST /api-keys/{id}/revoke` |
| Billing | `GET /billing/plans`, `GET /billing/invoices` |
| Audit | `GET /audit-logs`, `GET /audit-logs/export` |
| Reports | `GET /reports`, `POST /reports/{id}/run` |
| Plugins | `GET /plugins`, `POST /plugins/{id}/install` |
| Dashboard | `GET /dashboard/summary` |

## License

Proprietary - LandveX Enterprise Platform