System Architecture
This document is intended to be a complete look at the structure and layout of the Mobile Trail Mapping (MTM) system. It provides a set of functional requirements for the system, describes the architectural design patterns in use in the system's code, and shows aspects of the system's compartmentalization and dependencies. Users unfamiliar with the system should first consult the project requirements and expected use cases before beginning this document.
The Mobile Trail Mapping project is intended to be a complete suite of mobile and server applications that provide information and mapping services for the Linn County Trails System. Developed primarily for the Android and iOS platforms, the MTM applications provide users with the location of trails and points of interest across every trail in Linn County, Iowa, as well as additional information about certain landmarks and the ability to report problems within the trails system. The primary stakeholders in this system are the members of the Linn County Trails Association (LCTA), as well as any user of the trails in or near Cedar Rapids, Iowa. By April 2011, the MTM team intends to deliver two mobile applications and a server-side backend for the use of the LCTA. For more details, see the project problem statement.
The MTM system has a complete set of functional requirements documented at the requirements and use cases pages; refer to those documents for full requirements information. Briefly, the key functional requirements for the MTM system are:
- Provide a server backend with a simple, remotely accessible API
- Integrate fully with the existing LCTA site
- Support authentication of users for management purposes
- Integrate with Google Maps for display of trails and landmark information
- Allow posts back to the server with geotagged, photographic information
In addition to the functional requirements outlined above, the MTM system must adhere to a certain set of quality attributes as well. The following subsections detail the precise attributes a finalized MTM system must have.
Availability - The trails system does not completely close, per se, at any point; as such, even though individual trails may be closed, the MTM system must be available as much as possible. If necessary, downtime must be concentrated during the evenings or in winter, when trail usage is likely to be much lower.
Source: End users
Stimulus: Regular usage
Environment: Any operating environment or condition
Artifact: Server backend (the MTM team cannot control uptime of individual mobile applications)
Response: Provide expected trails data and landmark information to mobile application and accept any problem reports or authorization actions, or display notification of server downtime
Measure: Time before response (either expected or downtime notification) reaches user
Functionality - The MTM system, when up, must operate within the constraints imposed by the requirements document, the mobile application, and the end user; generally, this means handling data as it is provided and requested, and not encountering any unexpected system terminations.
Source: End user
Stimulus: Normal usage
Environment: Normal operating environment
Artifact: Entire system
Response: Respond to user data as specified in use cases
Measure: Time to expected response is delivered (taking into account network delay)
Usability - As most of the expected users of the MTM system are decidedly nontechnical, usability is an extremely important quality attribute for the mobile applications. The team will be following the restrictions laid out by the Apple Human Interface Guidelines and the Android user interface recommendations.
Source: End user
Stimulus: Normal use
Environment: Normal operating environment
Artifact: Mobile application user interface
Response: Provide a consistent, clean, intuitive interface; respond quickly to user requests
Measure: Ratio of successful to unsuccessful actions; number of clicks to desired user action
Security - While the trail data itself is public, some information (such as authenticated user credentials) must be stored and transmitted securely within the MTM system. Keeping this information secure protects the integrity of the trails data.
Source: Unauthorized user
Stimulus: Authorization request via mobile application
Environment: Normal operating environment
Artifact: Server authentication mechanism
Response: Deny authentication request
Measure: Number of unauthorized users allowed access; percentage of authorized requests incorrectly denied
Testability - In order to ensure many of the other quality attributes in this list, the MTM system must be developed in a way that allows for easy testing. Being able to properly test the system will make it much easier for developers to discover errors in functionality, usability, and availability. Note that such errors will be hidden from the user in release builds, and exposed primarily in debugging and testing processes.
Source: Developers
Stimulus: SickBeard system must undergo unit and acceptance testing
Environment: Development and deployment
Artifact: All MTM applications
Response: Able to locate and run tests over system-level methods and architecture objects, and confirm system at all levels is running properly
Measure: Time taken to locate and run tests; time taken to run tests; test passed vs. tests failed
Modifiability - The primary maintainer of the MTM system after May 2011 will be members of the LCTA, who are not paid or full-time developers; as such, the system must be as well-documented and easy to maintain as possible. In addition, since the MTM system is an open-source project, being able to easily modify the code is an important aspect of the system. MTM applications should be easy for new developers to understand and make meaningful contributions to.
Source: Developers
Stimulus: Changes need to be made to the MTM system
Environment: Development, testing, deployment
Artifact: Any MTM application
Response: Able to locate place in code to modify and make desired change with a minimum of searching and debug effort
Measure: Time taken to locate target code; time spent making change; time spent debugging and verifying proper behavior
In order to further enhance the quality of the MTM system as measured by the attributes listed above, the team is following established object-oriented design practices, including the use of known object structural patterns.
Availability - The MTM team is relying largely on the underlying platforms' reliability to ensure a high uptime of the platform itself. As such, the availability of the system will be largely determined by the reliability of the actual executable code; to ensure a solid system in this regard, the team is providing unit testing on all critical code paths, to ensure that all queries - even invalid ones - are met with the appropriate response, and that no query triggers a system malfunction. The team is also turning to the established practices in the area of exception handling (which vary platform to platform).
Functionality - In order to ensure the appropriate functionality is implemented simply, the MTM team is keeping the representation gap as low as possible. The object design within the database (and, hence, the model provided within the code of the mobile applications) mirrors actual trails system concepts (e.g. trail point, point of interest, etc.). This strategy is a common practice within the object-oriented design community.
Usability - The usability tactics are largely proscribed by the Apple and Android policies; the MTM team will follow these guidelines as closely as possible. In addition, the team will seek to extend the fluid and intuitive behavior provided by Google Maps on both mobile platforms.
Security - Security is an end-to-end concern for the MTM team. The unit tests put in place by the team will include possibly dangerous inputs, to ensure that appropriate sanitization takes place. Furthermore, frameworks in place on the mobile devices themselves will provide secure storage for user data such as login credentials.
Testability - Testing is an area of focus for the MTM team. The entire system is being developed under a test-driven process, which includes everything from writing tests at the individual method level to defining data-validating XML schemas for data transfer. As such, the team is forced during development to ensure that methods are compartmentalized appropriately and all individually provide valid responses, increasing confidence in the appropriate behavior of the system as a whole.
Modifiability - The representational structure and test-driven development described above also contributes to modifiability; since the system closely mirrors reality, it should be relatively simple to understand and modify conceptually, and the existence of a corpus of tests makes it simple to ensure that no change breaks the system or triggers a regression in behavior.
The MTM system is, by its nature, quite hierarchical. The primary breakdown is into the three major components under development by the team: the Android application, iPhone application, and server backend application. It is this architecture which drives the remainder of the design of the system.
Since the Internet is the primary communications framework between the three pieces, the team must focus on two separate concerns:
- How does each piece work as a standalone unit/how can the team architect each part of the system?
- How can the team make each piece communicate effectively over the Internet?
This section describes the structures in place for each of the three major parts of the MTM system. It provides a look at both the programmatic layout of the components, as well as the underlying infrastructure that supports those components.
The server component of the MTM system is a reasonably small system that builds on several different frameworks, primarily provided via the Ruby Gems system. It provides model classes for each conceptual object within the system (trails, points, conditions, etc.), matching each class with a backing database object, which is stored in an SQLite data store accessed via the Datamapper gem. These classes are tied together by means of a primary handler, which accepts incoming HTTP requests, performs user validation and API key checking, then dispatches an action the appropriate model class. This architecture is illustrated below.
This structure is dependent on a large number of underlying components, starting at the level of the server hardware and working up through the language environment and frameworks. In the following diagram, green components are those the team installs and administers explicitly; yellow are those provided by the hosted environment, but configurable by the MTM team; and red are those which cannot be altered except by means of complete environment change. (The white components indicate additional applications that share server space and allocation with the team's software stack, but which are part of separate environments and do not concern the execution of the MTM application.)
The Android MTM application provides a thin layer atop the general data models for trails, points, and other domain concepts.
The application integrates with the provided Android frameworks for GPS location, Google Maps, and network services to provide the user interface; these services are coordinated by the underlying Android operating system and phone hardware. The application itself is managed by the Dalvik scheduler and application launcher.
The iPhone MTM application was designed after the Android application, and as such shares much of its architecture and guiding principles. It too is a thin layer that wraps data models into a user-friendly interface for iOS systems.
The application integrates with existing iOS frameworks:
- UIKit for user interfaces
- MapKit for Google Maps and location data
- CoreLocation for GPS data and supporting classes
These services are coordinated by the underlying iOS structures and phone hardware. The application runs within the multitasking framework of iOS 4.0.
Due to the disparate nature of the various components involved, the team chose as unified a communications language as possible: XML. By providing a standardized schema for all XML transmissions between the mobile applications and server, the team can ensure not only that the data is portable and has a wide range of platform support, but is also extensible and can be validated easily. The XML structure in use is illustrated below.
The MTM system can be cleanly divided into three major portions (as shown above): the server backend, an Android application, and an iPhone application. Each of these components relies heavily on one large framework for its functionality.
Server Application - The MTM team is using the Ruby framework Sinatra for the development of the server. Sinatra provides easy and intuitive ways to develop web applications and serve data, while at the same time allowing the team to use the power and flexibility of the Ruby language. The primary abstraction provided by Sinatra lies in the handling of web requests. Sinatra contains a built-in HTTP server and automatically translates requests it receives into easily parseable objects. Furthermore, it allows the developer to define a set of functions that are automatically called when a matching request is received. In providing this functionality, Sinatra frees the developer from the requirement of handling the technicalities of HTTP service explicitly.
Android Application - The MTM application for Android will be built entirely on the Android framework and SDK, a Java-based platform developed by Google and made publicly available for Android developers. The framework provides a familiar way for object-oriented developers to interact with the phone hardware and other APIs available via Google (most notably Google Maps, which is integrated into the framework). One of the Android framework's defining features is its "activity lifecycle," a set of events that are triggered at certain points during the application's execution. By working within the lifecycle, the team can ensure the Android application provides a smooth, intuitive user experience.
iPhone Application - In a similar vein, the iPhone MTM application will be dependent on Apple's iOS SDK and all the frameworks it provides. The most unique part of the iOS SDK is the set of UI components provided; since Apple is very stringent about their usability and interface guidelines, the team must constrain themselves to using only the UIKit interface components that are provided.