# urban-toolkit/curio architecture

> Architecture diagram of the GitHub repository urban-toolkit/curio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urban-toolkit/curio
- Repository: https://github.com/urban-toolkit/curio

## Overview

##### Project Type and Purpose
- Curio is a full‐stack framework focused on collaborative urban visual analytics. It leverages a dataflow model to integrate preprocessing, management, and visualization of urban data. The project also stresses provenance awareness and collaboration, with integrations to UTK, Vega-Lite, and external authentication (e.g., Google OAuth).

##### And Identify Main Components
- Backend Service (in the “backend” directory):
- Contains the Flask-based API server (server.py), configurations (config.py, .flaskenv), and database migration scripts (Alembic migrations).
- Manages the core business logic, provenance tracking, user authentication (note presence of Google OAuth service), and data flow orchestration.
- Includes modules for API routing (api/routes.py), middleware, and user models.
- Frontend / Visualization Components (in “urban-workflows”):
- A modern React/TypeScript-based application structured under the “urban-workflows/src” directory.
- Incorporates high-level grammar and handles the user interface for interactive visual analytics.
- Sandbox Environment:
- Found in the “sandbox” directory, this appears to be a deployment/testing environment that closely mirrors the backend but may provide additional tools (docker-compose, Dockerfile) to run the application in isolated settings.
- Documentation and Examples:
- Located under the “docs” folder which includes guidelines, code style, and usage examples.
- External Integrations:
- Integration with external services including Google OAuth (visible in backend’s services), UTK visualization framework, and Vega-Lite for charting.

##### Relationships and Interactions
- The frontend (urban-workflows) interacts with the backend API to:
- Submit user actions and data for processing.
- Retrieve analysis results and provenance information.
- The backend’s API routes enforce business logic, call external services (Google OAuth for authentication), and interact with the database (migration files, Provenance.sql, user models).
- Sandbox serves as an alternative deployment configuration and may be used for local testing, containerized deployments, or rapid prototyping.
- Dataflow: The system relies on a clear dataflow model—from data ingestion and preprocessing (in the backend), through processing and provenance capture, to visual presentation on the frontend.

##### Important Architectural Patterns and Design Principles
- Modular design: Separation of concerns is evident across different directories (API, services, users for backend; components and providers in frontend).
- Provenance-aware data tracking is a core design element to track every transformation along the dataflow.
- Use of micro-frontend or component-based architectures in the urban-workflows (React components).
- Configuration and environment separation (see different .flaskenv files and sandbox-specific configurations).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Integrations
    subgraph "External Integrations"
        ext1["UTK Visualization"]:::external
        ext2["Vega-Lite Charts"]:::external
    end

    %% Sandbox Environment
    subgraph "Sandbox Environment"
        sb_api["Sandbox API (server)"]:::sandbox
        sb_app_api["Sandbox App API"]:::sandbox
        dockerfile["Dockerfile"]:::sandbox
        docker_compose["docker-compose.yaml"]:::sandbox
    end

    %% Backend System
    subgraph "Backend System"
        api_server["Flask API Server"]:::backend
        api_routes["API Routes"]:::backend
        middleware["Middleware"]:::backend
        google_oauth["Google OAuth Module"]:::backend
        user_mgmt["User Management"]:::backend
        config["Config (config.py)"]:::backend
        flaskenv[".flaskenv"]:::backend
        db_schema["Database Schema (Provenance.sql)"]:::backend
        migrations["Migrations"]:::backend
    end

    %% Frontend Application
    subgraph "Frontend Application"
        react_app["React/TypeScript App"]:::frontend
        ui_components["UI Components"]:::frontend
        providers["Providers"]:::frontend
        dataclean["DataCleaning.tsx"]:::frontend
        dataexport["DataExportBox.tsx"]:::frontend
        vegabox["VegaBox.tsx"]:::frontend
        commentsbox["CommentsBox.tsx"]:::frontend
        flowprovider["FlowProvider.tsx"]:::frontend
        provenanceprovider["ProvenanceProvider.tsx"]:::frontend
        templateprovider["TemplateProvider.tsx"]:::frontend
        userprovider["UserProvider.tsx"]:::frontend
    end

    %% Documentation and Examples
    docs_node["Documentation & Examples"]:::docs

    %%------------------------------------------------------------------------------
    %% Connections
    %% Frontend interacting with Backend
    react_app -->|"API_call"| api_server
    react_app -->|"uses"| ui_components
    react_app -->|"utilizes"| providers

    %% Providers provide support to UI Components
    providers --> flowprovider
    providers --> provenanceprovider
    providers --> templateprovider
    providers --> userprovider

    %% UI Components breakdown
    ui_components --> dataclean
    ui_components --> dataexport
    ui_components --> vegabox
    ui_components --> commentsbox

    %% UI Components calling external visualization libraries
    ui_components -->|"calls"| ext1
    ui_components -->|"calls"| ext2

    %% Backend internal modules
    api_server -->|"routes"| api_routes
    api_server -->|"uses"| middleware
    api_server -->|"authenticates_via"| google_oauth
    api_server -->|"manages"| user_mgmt

    %% Backend configuration and database
    api_server -->|"reads"| config
    api_server -->|"reads"| flaskenv
    api_server -->|"queries"| db_schema
    api_server -->|"operates_on"| migrations

    %% Sandbox forwarding to Backend
    sb_api -->|"proxies"| api_server
    sb_app_api -->|"proxies"| api_server
    dockerfile -->|"configures"| sb_api
    docker_compose -->|"orchestrates"| sb_api

    %% Documentation linked to system components
    docs_node --- react_app
    docs_node --- api_server

    %%------------------------------------------------------------------------------
    %% Styles
    classDef backend fill:#CCEEFF,stroke:#333,stroke-width:2px;
    classDef frontend fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef sandbox fill:#FFDDAA,stroke:#333,stroke-width:2px;
    classDef external fill:#FFCCFF,stroke:#333,stroke-width:2px;
    classDef docs fill:#EEEEEE,stroke:#333,stroke-width:2px;

    %%------------------------------------------------------------------------------
    %% Click Events
    click api_server "https://github.com/urban-toolkit/curio/blob/main/backend/server.py"
    click api_routes "https://github.com/urban-toolkit/curio/blob/main/backend/app/api/routes.py"
    click middleware "https://github.com/urban-toolkit/curio/blob/main/backend/app/middlewares.py"
    click google_oauth "https://github.com/urban-toolkit/curio/blob/main/backend/app/services/google_oauth.py"
    click user_mgmt "https://github.com/urban-toolkit/curio/blob/main/backend/app/users/models.py"
    click config "https://github.com/urban-toolkit/curio/blob/main/backend/config.py"
    click flaskenv "https://github.com/urban-toolkit/curio/blob/main/backend/.flaskenv"
    click db_schema "https://github.com/urban-toolkit/curio/blob/main/backend/Provenance.sql"
    click migrations "https://github.com/urban-toolkit/curio/tree/main/backend/migrations"

    click react_app "https://github.com/urban-toolkit/curio/tree/main/urban-workflows/src"
    click ui_components "https://github.com/urban-toolkit/curio/tree/main/urban-workflows/src/components"
    click providers "https://github.com/urban-toolkit/curio/tree/main/urban-workflows/src/providers"
    click dataclean "https://github.com/urban-toolkit/curio/blob/main/urban-workflows/src/components/DataCleaning.tsx"
    click dataexport "https://github.com/urban-toolkit/curio/blob/main/urban-workflows/src/components/DataExportBox.tsx"
    click vegabox "https://github.com/urban-toolkit/curio/blob/main/urban-workflows/src/components/VegaBox.tsx"
    click commentsbox "https://github.com/urban-toolkit/curio/blob/main/urban-workflows/src/components/CommentsBox.tsx"
    click flowprovider "https://github.com/urban-toolkit/curio/blob/main/urban-workflows/src/providers/FlowProvider.tsx"
    click provenanceprovider "https://github.com/urban-toolkit/curio/blob/main/urban-workflows/src/providers/ProvenanceProvider.tsx"
    click templateprovider "https://github.com/urban-toolkit/curio/blob/main/urban-workflows/src/providers/TemplateProvider.tsx"
    click userprovider "https://github.com/urban-toolkit/curio/blob/main/urban-workflows/src/providers/UserProvider.tsx"

    click sb_api "https://github.com/urban-toolkit/curio/blob/main/sandbox/server.py"
    click sb_app_api "https://github.com/urban-toolkit/curio/blob/main/sandbox/app/api.py"
    click dockerfile "https://github.com/urban-toolkit/curio/tree/main/sandbox/Dockerfile"
    click docker_compose "https://github.com/urban-toolkit/curio/blob/main/sandbox/docker-compose.yaml"

    click docs_node "https://github.com/urban-toolkit/curio/tree/main/docs"
```
