diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 3add0984..485bd41c 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -4,22 +4,28 @@ NOTE: This is intentionally hand-wavy in some parts, and will be formalized more ## Repo Structure -Monorepo-ish.... It would be pointless to split up the core repos to be honest. Unfortunately, the iOS UI will probably have -to be split out because of the "feature" of Swift packages being tied to the root of a git repo. +To ensure that everything can be developed properly in parallel, +we use a monorepo structure. +This, combined with CI, will ensure that changes in the core must be immediately reflected in frontends +like Apple and Android.. -## Common core +## Core (`common`) -These components will be standardized and cross-platform. We chose to write this in Rust as it lacks most of the headaches +Common logic is shared across platforms via the common core. +We chose to write this in Rust as it lacks most of the headaches associated with C++, has interoperability with just about every platform. Recently, there have been huge strides in idiomatic binding generation for Swift and Kotlin (see [UniFFI](https://github.com/mozilla/uniffi-rs) from Mozilla), and Rust has some of the most loved build tooling of any programming language. ### Navigation Controller -This manages the lifecycle of the navigation (TODO: define this more precisely). When it receives an -update on the user's current location, it decides whether the user is still on course, initiates -recalculation if necessary and desired, and pushes updates to the Navigation UI. The navigation controller -exposes information to the outside via a state model that can be used to update the frontend UI (platform-specific). +This manages the lifecycle of the navigation (TODO: define this more precisely). +When it receives an update on the user's current location, +it decides whether the user is still on course, +initiates recalculation if necessary and desired, +and pushes updates to the Navigation UI. +The navigation controller exposes information to the outside via a state model +that can be used to update the frontend UI (platform-specific). ### Routing Adapters @@ -49,18 +55,24 @@ from the perspective of app code. - Provide simulated/mocked location and network for testing where appropriate - Enable extensibility (ex: local route generation, deciding whether to recalculate, etc.) -### Navigation UI +### UI Ferrostar seeks to provide a default navigation UI for major platforms at the discretion of the core team. Default navigation UI implementations seek to provide a sensible experience which could be used for the majority of common routing use cases. -We assume that most devs will want this, -that it should be customizable within reason, -and will strive to make the implementation modular (ex: via SwiftUI controls) -so that devs may compose default implementations with their own. + +We assume that most devs will want *some* flavor of this, +but that it should be customizable within reason. +As such, we do our best to make the implementation modular +(ex: via SwiftUI and JetPack Compose reusable components). +This way, devs may compose default implementations with their own. Current platforms for which the core team maintains a UI: * iOS (SwiftUI + MapLibre) * Android (Jetpack Compose + MapLibre) + +Note that while the currently bundled UI libraries utilize MapLibre, +there is no strong coupling. +You may add your own UI utilizing basemaps from any other vendor.