diff --git a/docs/index.rst b/docs/index.rst index be04bee..89d3d70 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -24,6 +24,7 @@ include: :maxdepth: 2 :caption: Documentation: + narr/intro narr/install narr/auth narr/features diff --git a/docs/narr/intro.rst b/docs/narr/intro.rst new file mode 100644 index 0000000..4466d25 --- /dev/null +++ b/docs/narr/intro.rst @@ -0,0 +1,123 @@ + +============== + Introduction +============== + +This page hopefully conveys the what and why of WuttaFarm as a project. + +WuttaFarm can serve as a "supplement" or "alternative" to `farmOS +`_, depending on your needs. It has 3 distinct +"modes" of operation: + +* :ref:`wrapper (API only) ` +* :ref:`mirror (2-way sync) ` +* :ref:`standalone ` + + +Rationale +--------- + +This project exists primarily to scratch a personal itch, but the hope +of course is that others will find it useful also. This is partly why +the app has different integration modes. + +Realistically this is not (yet?) meant to be a "finished" app per se. +In that sense it is akin to farmOS itself, i.e. "part app, part +framework" which can be extended where needed. + +It purposefully does not try to re-invent every wheel provided by +farmOS. But it does re-invent "certain types" of wheels, to some +degree, depending on which mode is used. + +It should also be mentioned, the 3 "modes" are essentially just +abstractions for sake of convenience. The framework allows one to +customize however you want regardless of the "mode" in effect. + +The target audience I suppose, is folks like me who prefer Python over +PHP, and can customize away without having to touch Drupal. + + +.. _wrapper-mode: + +Wrapper Mode (API only) +----------------------- + +This is the default integration mode for the app. In wrapper mode, +WuttaFarm UI will only expose views which display/modify farmOS data +*directly* via its JSONAPI. The app will not expose any views which +operate on its "native" tables (for assets, logs etc.). + +Any data model extensions needed must of course be managed on the +farmOS side, since the native tables are not used for this mode. + +This mode is simplest (for farmOS integration) since every user action +goes immeditely through the API. There is no "sync" or caching +involved. + +There is one known issue with this mode, and it's kind of a bummer: + +When viewing the "list" page for any record type (e.g. Animal Assets), +due to a quirk with the JSONAPI, you can only see the "first 50" +results in the listing. However you can still filter/sort the +records, to hopefully find what you need. And you can still view +*any* record if you have its URL (which you can normally figure out +from the farmOS UUID value). + + +.. _mirror-mode: + +Mirror Mode (2-way sync) +------------------------ + +This mode exposes the native table views in addition to direct API +views. It's sort of a combination of the wrapper and standalone +modes, with an extra daemon process to handle some of the sync tasks. + +(It's also the most complex mode to setup; more "moving parts" which +means potentially more to go wrong and require troubleshooting.) + +Again this depends on your actual use case, but a "complete" setup for +this mode would mean: + +* changes made in WuttaFarm are synced to farmOS via JSONAPI +* changes made in farmOS are synced to WuttaFarm via webhook+daemon + +The latter includes changes made via the farmOS proper web app, and/or +changes made via the "direct API" views within WuttaFarm (or anything +else that invokes the farmOS API). This requires the extra daemon +process (running alongside the WuttaFarm web app process), as well as +the `webhooks module +`_ on +the farmOS side. + +It's possible to extend the data model on the WuttaFarm side with or +without doing so on the farmOS side, and vice versa. Although +regardless you may have to take both into consideration for your +overall sync needs. + +There is support for "full" data import/export between systems in both +directions, WuttaFarm <=> farmOS. Limited of course by the common +schema they share etc. This can be leveraged easily to include +nightly "data diff" checks, ensuring all stays in sync. + + + +.. _standalone-mode: + +Standalone Mode +--------------- + +This mode exposes *only* the native table views, and none of the +"direct API" views. This requires no farmOS at all. + +This lets you customize the data model as needed, using SQLAlchemy and +Alembic, as does the mirror mode. However no "sync" is required so +you don't have to consider the farmOS data model. + +While the wrapper mode is simplest for farmOS integration, this +standalone mode is even simpler, technically speaking. It should work +well if you just need the basic record-keeping aspects. + +The main downside with this mode is there is not (yet?) any +mapping/geometry support, nor is there support for image/file +attachments.