How lbouma/cyclopath works
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”