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

# Start all services
docker-compose up -d

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

Environment Variables

# 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