Differences between revisions 3 and 4
Revision 3 as of 2017-08-03 14:24:04
Size: 3706
Editor: KeeganQuinn
Comment: document design notes, quality standards, rationale and plans for zones
Revision 4 as of 2017-08-03 15:26:25
Size: 5553
Editor: KeeganQuinn
Comment: nodes, geocoding
Deletions are marked like this. Additions are marked like this.
Line 34: Line 34:
=== Node ===

Node: Descends from Zone, has Hosts as children. Node is pretty well off. Kinda the main attraction around here.

Nodes can be assigned a street address; address will be geocoded on save and results will be stored as the node's latitude and longitude; nodes with valid latitude and longitude values will be displayed on maps. Latitude and longitude cannot be set directly, they can only be populated by geocoding the address.

Note that the previous node database system included both street address and lat/long values; based on a report that at least one lat/long value in that source data was incorrect, all points for imported nodes were re-geocoded at import time based on the street address values.

Although users have requested the ability to set lat/long values directly, it's my strong feeling that the geocoding implementation really needs to work correctly and reliably, and that allowing users to override the geocoder is not an appropriate way of dealing with a broken geocoder. Normal users navigate by using street addresses, not coordinates, and when we plot a point on a map with an address displayed on it, those same normal users are going to expect that point coincides with that address. It's a reasonable expectation, one we should not subvert.

Unfortunately for us all, correct and reliable geocoding is apparently quite a difficult problem, particularly for a non-profit that is unable to pay access fees to a commercial geocoding service. Thus far we have used both the Google Maps lookup service and the !OpenStreetMaps Nominatim lookup service, both with mixed results; currently, neither service is able to produce correct points for all node addresses. We've worked around this in live for now, but sooner or later we will need to address this with a comprehensive geocoding solution.


cwnmyr is an open-source community wireless network management platform developed to meet the needs of PersonalTelco. See Adhocracy for historical information. See the README on GitHub for technical information.

PersonalTelco cwnmyr: https://cwnmyr.personaltelco.net/

GitHub: https://github.com/keeganquinn/cwnmyr

Jenkins: https://quinn.tk/jenkins/job/cwnmyr/

Design Goals

This software is intended to simplify a number of aspects of community networking, both technical and logistical. It is capable of storing and aggregating many kinds of information about people (users and contacts), areas (zones), sites (nodes), network devices (hosts) and network interfaces. Other expected features include generating maps, graphs, and configuration files.

A comprehensive domain model forms the foundation of the application, using a relational database as a backing store and an object-oriented abstraction layer to provide a rich developer interface. Stored and transmitted values are normalized to avoid redundancy and maintain integrity. The specific types and attributes included in the model have been selected through a combination of domain research, peer discussion, and iterative development. It is intended to be as stable as possible over time, with changes made only after careful deliberation or in direct response to technical requirements.

Software quality is guaranteed by the application of modern agile engineering practices, with an emphasis on test-driven development and continuous integration. For contributions, we ask that all code includes passing tests, no regressions, and test coverage must remain over 90%.

Model Rationale

Zone

Zone: Top-level model, has Nodes as children. Zone is awkward right now.

Historically, node maintenance tasks around the city were delegated by quadrant, so each quadrant would have been a Zone, and each Zone would have had maintainers. We don't use quadrants any more, so we don't need Zones to represent them any more either; we now just have one big Zone called Portland. In the current site, our singular Zone doesn't really represent or differentiate anything, which makes it very tempting to get rid of Zones entirely and just have loose Nodes.

With that said, I've always found Zone conceptually appealing as a top-level container: holding it down at the root of the object graph like a boss. Instead of throwing it out, we can leverage the fact that we have exactly one Zone by making it the default, eliminating the confusing and redundant zone selection UI. With a default Zone, we can store zone-wide metadata, such as configuration values and branding assets.

I'd like to maintain support in the code for multiple Zones as well, even if we don't have any actual users for them now. A first visit to a cwnmyr site with multiple Zones should probably serve the default Zone immediately, or the database-first Zone if there is no default. It might also be nice to add support for detecting the Zone to show via URL or based on the user's source IP/location. Ideally I'd like this to work well enough that another CWN in another part of the world could just add a Zone to our cwnmyr and build out their own network using our tools.

Last but not least, I'd like for Zones to be portable between cwnmyr instances in some way, to allow possible support for decentralized operation down the line. For example, users might run a local cwnmyr instance to manipulate data or perform a build while offline, then sync their changes with a central instance when they regain connectivity.

Node

Node: Descends from Zone, has Hosts as children. Node is pretty well off. Kinda the main attraction around here.

Nodes can be assigned a street address; address will be geocoded on save and results will be stored as the node's latitude and longitude; nodes with valid latitude and longitude values will be displayed on maps. Latitude and longitude cannot be set directly, they can only be populated by geocoding the address.

Note that the previous node database system included both street address and lat/long values; based on a report that at least one lat/long value in that source data was incorrect, all points for imported nodes were re-geocoded at import time based on the street address values.

Although users have requested the ability to set lat/long values directly, it's my strong feeling that the geocoding implementation really needs to work correctly and reliably, and that allowing users to override the geocoder is not an appropriate way of dealing with a broken geocoder. Normal users navigate by using street addresses, not coordinates, and when we plot a point on a map with an address displayed on it, those same normal users are going to expect that point coincides with that address. It's a reasonable expectation, one we should not subvert.

Unfortunately for us all, correct and reliable geocoding is apparently quite a difficult problem, particularly for a non-profit that is unable to pay access fees to a commercial geocoding service. Thus far we have used both the Google Maps lookup service and the OpenStreetMaps Nominatim lookup service, both with mixed results; currently, neither service is able to produce correct points for all node addresses. We've worked around this in live for now, but sooner or later we will need to address this with a comprehensive geocoding solution.

More

(other models and information TBD)


[CategorySoftware]

CwnmyrProject (last edited 2017-08-03 15:26:25 by KeeganQuinn)