# lbouma/cyclopath architecture

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

- Interactive diagram: https://gitdiagram.com/lbouma/cyclopath
- Repository: https://github.com/lbouma/cyclopath

## Overview

##### Project Type & Purpose
- Cyclopath is a full-stack, multi-channel geowiki platform. It serves map data and wiki-style item editing via:
- Native Android client (“android/…”)
- Flash/Flex web client (“flashclient/…”, hosted under “htdocs/…”)
- Standard web pages (“htdocs/…”)
- Background services (Python daemons in “services/…”)
- Cron and one-off scripts (“scripts/…”)
- The Python “pyserver/…” module is the core application server (API layer), communicating via a custom RPC protocol (GWIS) and accessing a Postgres/PostGIS database.

##### High-Level Component Breakdown
- Clients
- Android App → GWIS calls to pyserver, HTTP fetch of map tiles from MapServer
- Flash Web App → SWF served by Apache, uses GWIS RPC & static JS widgets
- Static pages & JS widgets under “htdocs” for non-Flash browsers
- Web/API Tier
- Apache / mod_python → dispatches GWIS endpoints to pyserver
- pyserver
– GWIS command/query handlers (pyserver/gwis/…)
– Business logic: item management (“pyserver/item/…”), access control (pyserver/grax/…), route planning (pyserver/planner/…), utility modules (pyserver/util_/…)
– Integrates rpy2 for advanced analysis (in pyserver/bin/rpy2)
– MediaWiki extension (“mediawiki/extensions/CycloAuth.php”) for wiki pages
- & Tile Tier
- MapServer (Perl/Python scripts under “mapserver/…”)
- Tilecache updates triggered by periodic scripts and on-demand requests
- Data Tier
- PostgreSQL with PostGIS
- Schema managed by “scripts/schema/…”
- Background Services & Batch
- Long-running daemons in “services/…”:
– mr_do (job dispatcher)
– conflation service (map data merging)
– merge service (batch import/export across branches)
– route_analysis service (precompute routing profiles)
– “routed” (routing web service)
- Cron and “scripts/daily”, “scripts/dev” jobs for exports, imports, maintenance, analytics
- External Integrations
- Geocoding (GWIS_Geocode)
- Link shortening, stats, Google transit feeds
- MediaWiki, Bugzilla templates, etc.

##### Key Architectural Patterns
- Layered Separation: Client ⇄ API ⇄ Data
- Command/Query – GWIS divides read/query vs. write/command logic
- Event-driven Workers: background daemons poll DB tables or job queues
- Microservices: each “services/…” piece runs as its own daemon
- Plugin-style modules: access control (Grax), item types, map “skins”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Clients Layer
  subgraph "Clients" 
    classDef client fill:#cde,stroke:#36c,stroke-width:2px
    Android["Android Client (Java)"]:::client
    Flash["Flash/Flex Client (ActionScript)"]:::client
    Static["Static Web Frontend (HTML/JS)"]:::client
  end

  %% API / Web Tier
  subgraph "API/Web Tier"
    classDef api fill:#cfc,stroke:#2a2,stroke-width:2px
    Apache["Apache Web Server (mod_python)"]:::api
    subgraph "pyserver Application Server (Python GWIS)"
      classDef core fill:#cfc,stroke:#090,stroke-width:1px
      PyCore["Entry & Config (ccp.py, conf.py, g.py)"]:::core
      GWIS["GWIS Handlers"]:::core
      Logic["Business Logic Modules"]:::core
      Rpy2["rpy2 Integration (R)"]:::core
      MediaWiki["MediaWiki Extension"]:::core
    end
  end

  %% Map & Tile Tier
  subgraph "Map & Tile Tier"
    classDef mapbox fill:#fcc,stroke:#c33,stroke-width:2px
    MapServer["MapServer + Tilecache"]:::mapbox
  end

  %% Data Tier
  subgraph "Data Tier"
    classDef data fill:#eee,stroke:#999,stroke-width:2px
    PostGIS["PostgreSQL/PostGIS"]:::data
  end

  %% Background Services & Batch
  subgraph "Background Services"
    classDef service fill:#fc9,stroke:#f60,stroke-width:2px
    mr_do["mr_do Dispatcher"]:::service
    conflation["Conflation Service"]:::service
    merge["Merge Service"]:::service
    route_analysis["Route Analysis Service"]:::service
    routed["routed Web Service"]:::service
  end

  %% Cron & Scripts
  subgraph "Cron Jobs & One-off Scripts"
    classDef batch fill:#ffd,stroke:#dd0,stroke-width:2px
    Cron["Cron & Scripts"]:::batch
  end

  %% External Integrations
  subgraph "External Services" 
    classDef external fill:none,stroke:#666,stroke-dasharray: 5 5
    Geocode["Geocoding API"]:::external
  end

  %% Connections
  Android -->|HTTP/S| Apache
  Flash -->|HTTP/S| Apache
  Static -->|HTTP/S| Apache

  Apache -->|GWIS RPC| PyCore
  Apache -->|GWIS RPC| GWIS

  PyCore -->|uses| Logic
  Logic -->|invokes| GWIS
  GWIS -->|calls| Logic
  GWIS -->|executes| Rpy2
  GWIS -->|auth via CycloAuth| MediaWiki

  GWIS -->|SQL reads/writes| PostGIS
  GWIS -->|HTTP tile requests| MapServer
  GWIS -->|Geocode RPC| Geocode

  MRdoInput([Job Queue]) --- mr_do
  Cron -->|schedules jobs| PostGIS
  Cron -->|runs| mr_do
  mr_do -->|dispatch jobs| PyCore
  mr_do -->|dispatch| MapServer

  conflation -->|reads/writes| PostGIS
  merge -->|reads/writes| PostGIS
  route_analysis -->|writes profiles| PostGIS
  routed -->|serves| Apache

  %% Click Events
  click Android "https://github.com/lbouma/cyclopath/tree/release/android/src/org/cyclopath/android/"
  click Flash "https://github.com/lbouma/cyclopath/tree/release/flashclient/"
  click Static "https://github.com/lbouma/cyclopath/tree/release/htdocs/"
  click Apache "https://github.com/lbouma/cyclopath/blob/release/pyserver/pyserver_glue.py"
  click PyCore "https://github.com/lbouma/cyclopath/blob/release/pyserver/ccp.py"
  click GWIS "https://github.com/lbouma/cyclopath/tree/release/pyserver/gwis/"
  click Logic "https://github.com/lbouma/cyclopath/tree/release/pyserver/item/"
  click MapServer "https://github.com/lbouma/cyclopath/tree/release/mapserver/"
  click PostGIS "https://github.com/lbouma/cyclopath/tree/release/scripts/schema/"
  click mr_do "https://github.com/lbouma/cyclopath/blob/release/services/mr_do.py"
  click conflation "https://github.com/lbouma/cyclopath/blob/release/services/conflation/conflation.py"
  click merge "https://github.com/lbouma/cyclopath/tree/release/services/merge/"
  click route_analysis "https://github.com/lbouma/cyclopath/blob/release/services/route_analysis/route_analysis.py"
  click routed "https://github.com/lbouma/cyclopath/blob/release/services/routed.py"
  click Cron "https://github.com/lbouma/cyclopath/tree/release/scripts/daily/"
  click Geocode "https://github.com/lbouma/cyclopath/blob/release/pyserver/gwis/command_/geocode.py"

  %% Styles
  classDef client fill:#cde,stroke:#36c,stroke-width:2px
  classDef api fill:#cfc,stroke:#2a2,stroke-width:2px
  classDef core fill:#cfc,stroke:#090,stroke-width:1px
  classDef mapbox fill:#fcc,stroke:#c33,stroke-width:2px
  classDef data fill:#eee,stroke:#999,stroke-width:2px
  classDef service fill:#fc9,stroke:#f60,stroke-width:2px
  classDef batch fill:#ffd,stroke:#dd0,stroke-width:2px
  classDef external fill:none,stroke:#666,stroke-dasharray: 5 5
```
