Requirements and Architecture(Draft)

[davidgamez]

License-as-a-Service (LaaS) - Requirements and Architecture

• Must Have

  • Keep the standard licenses' source of truth as the GitHub repository
  • Maintain a clear distinction between standard and custom licenses in the database.
  • Ensure uniqueness of custom licenses by comparing their permission/condition/limitation mappings.
  • Sync standard licenses from a GitHub repo on demand.
  • Docker container for local and cloud deployment.
  • Provide a RESTful API with pagination, filtering, and proper OpenAPI schema.
  • Allow CRUD operations for custom licenses only. Prevent CRUD access to standard licenses (read-only from GitHub).

• Should Have

  • Optional API key-based authentication.
  • CORS origin restrictions for frontend security.
  • PostgreSQL search enhancements (e.g., pg_trgm).

• Could Have

  • CLI tool or admin UI for sync management or license review.
  • Support typeahead and multi-field search over license name and code.

Architecture Overview

The system can optionally support authentication and cross-origin request validation, configurable per deployment:

• Authentication: Token-based authentication (e.g., API key or OAuth2) can be enabled to restrict access to API endpoints.
• CORS Enforcement: Requests can be limited to an allowed set of origins via CORS middleware.

These capabilities allow customization of security posture depending on deployment needs (e.g., public sandbox vs. internal usage).

The system offers "License as a Service" with the following architecture:

• Unified License Table: Both standard and custom licenses live in a single table distinguished by a type field.
• Rule Composition: Permissions, conditions, and limitations are attached via join tables.
• Search: Implemented via a database-agnostic service with fallback to full-text or trigram indexes if supported.
• Standard License Sync: Standard licenses are pulled from a GitHub repository into each instance on demand. These are immutable through the API and cannot be edited via CRUD operations.

Component Diagram

flowchart TD
  User[User] --> UI[Frontend/UI]
  UI --> API[API Server]
  API --> Licenses[(licenses DB)]
  API --> Catalog[(permissions / conditions / limitations)]
  Repo[GitHub Repo]
  Repo --> API

Loading

Milestones/Epics

1. M1 - Schema Finalization
2. M2 - Initial Backend APIs
3. M3 - Dockerization
4. M4 - Search Implementation

Database Schema

-- Unified license table
CREATE TABLE licenses (
    id UUID PRIMARY KEY,
    type TEXT NOT NULL CHECK (type IN ('standard', 'custom')),
    spdx_id TEXT UNIQUE, -- for standard
    code TEXT UNIQUE, -- for custom
    name TEXT NOT NULL,
    url TEXT,
    summary TEXT,
    created_at TIMESTAMP,
    updated_at TIMESTAMP
);

-- Custom building blocks
CREATE TABLE permissions (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    description TEXT
);

CREATE TABLE conditions (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    description TEXT
);

CREATE TABLE limitations (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    description TEXT
);

-- Join tables for rule composition
CREATE TABLE license_permissions (
    license_id UUID REFERENCES licenses(id) ON DELETE CASCADE,
    permission_id TEXT REFERENCES permissions(id),
    PRIMARY KEY (license_id, permission_id)
);

CREATE TABLE license_conditions (
    license_id UUID REFERENCES licenses(id) ON DELETE CASCADE,
    condition_id TEXT REFERENCES conditions(id),
    PRIMARY KEY (license_id, condition_id)
);

CREATE TABLE license_limitations (
    license_id UUID REFERENCES licenses(id) ON DELETE CASCADE,
    limitation_id TEXT REFERENCES limitations(id),
    PRIMARY KEY (license_id, limitation_id)
);

-- Optional: PostgreSQL-specific
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE INDEX idx_license_code_trgm ON licenses USING gin (code gin_trgm_ops);
CREATE INDEX idx_license_name_trgm ON licenses USING gin (name gin_trgm_ops);

Search Abstraction Layer

This is needed to support multiple database engines.

class PostgresSearchService(SearchService):
    def search_licenses(self, query, filters):
        # Uses ILIKE or pg_trgm if available
        pass

class SearchService:
    def search_licenses(self, query: str, filters: dict):
        raise NotImplementedError

class MySQLSearchService(SearchService):
    def search_licenses(self, query, filters):
        # Uses LIKE or MATCH AGAINST
        pass

Flask Integration Notes

To support configurable authentication and cross-origin access in Flask:

from flask import Flask, request, abort
from flask_cors import CORS
import os

app # Flask(__name__)
CORS(app, origins=os.getenv("ALLOWED_ORIGINS", "*").split(","))

API_KEY # os.getenv("API_KEY")

@app.before_request
def check_api_key():
    if API_KEY:
        key # request.headers.get("X-API-Key")
        if key !# API_KEY:
            abort(401, "Unauthorized")

• Use API_KEY to control access globally.
• Use ALLOWED_ORIGINS env var for CORS domain control.

OpenAPI Schema

openapi: 3.0.0
info:
  version: 1.0.0
  title: License Service
  description: |
    License-as-a-Service (LaaS) provides a unified API to manage standard and custom licenses composed of permissions, conditions, and limitations. It supports license syncing from GitHub, CRUD for custom licenses, pagination, filtering, search, and optional authentication and CORS policies.
  contact:
    name: MobilityData
    url: https://mobilitydata.org/
    email: api@mobilitydata.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0

tags:
  - name: licenses
    description: License Information
  - name: rules
    description: Rules associated with a license(permissions, conditions and limitations)
    
paths:
  /licenses:
    get:
      summary: Get all licenses
      tags:
        - licenses
      parameters:
        - in: query
          name: type
          schema:
            type: string
            enum: [standard, custom]
          description: Filter by license type
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            maximum: 100
          description: Max number of results to return
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
          description: Pagination offset
      responses:
        '200':
          description: A list of licenses
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/License'
    post:
      summary: Create a new custom license
      tags:
        - licenses      
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/License'
      responses:
        '201':
          description: License created                  

  /licenses/search:
    get:
      summary: Search licenses with typeahead
      tags:
        - licenses      
      parameters:
        - in: query
          name: q
          schema:
            type: string
          required: true
          description: The search query (matches name or code)
        - in: query
          name: limit
          schema:
            type: integer
            default: 10
            maximum: 50
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/License'

  /licenses/sync:
    post:
      summary: Sync standard licenses from GitHub
      tags:
        - licenses      
      responses:
        '200':
          description: Sync successful
        '500':
          description: Sync failed

  /licenses/{id}:
    get:
      summary: Get a specific license
      tags:
        - licenses      
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: License details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/License'

    put:
      summary: Update a custom license
      tags:
        - licenses      
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/License'
      responses:
        '200':
          description: License updated

    delete:
      summary: Delete a custom license
      tags:
        - licenses      
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '204':
          description: License deleted
          
  /permissions:
    get:
      summary: Get all permissions
      tags:
        - rules
      responses:
        '200':
          description: A list of permissions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RuleBlock'

  /permissions/{id}:
    get:
      summary: Get a permission by ID
      tags:
        - rules      
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuleBlock'

  /conditions:
    get:
      summary: Get all conditions
      tags:
        - rules      
      responses:
        '200':
          description: A list of conditions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RuleBlock'

  /conditions/{id}:
    get:
      summary: Get a condition by ID
      tags:
        - rules      
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A condition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuleBlock'

  /limitations:
    get:
      summary: Get all limitations
      tags:
        - rules      
      responses:
        '200':
          description: A list of limitations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RuleBlock'

  /limitations/{id}:
    get:
      summary: Get a limitation by ID
      tags:
        - rules      
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A limitation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuleBlock'

components:
  schemas:
    RuleBlock:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
    License:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum: [standard, custom]
        spdx_id:
          type: string
          nullable: true
        name:
          type: string
        url:
          type: string      
        permissions:
          type: array
          items:
            type: string
          description: List of permission identifiers
        conditions:
          type: array
          items:
            type: string
          description: List of condition identifiers
        limitations:
          type: array
          items:
            type: string
          description: List of limitation identifiers

  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.com/token
          scopes:
            read: Grants read access
            write: Grants write access