Understanding The FarmOS Codebase

I was recently introduced to the codebase for FarmOS (on github), and I was interested in understanding how it works. I’ve had no problem understanding the code itself, but the whole project is split up into so many smaller modules, it’s somewhat difficult trying to figure out how everything fits together, and what’s connected to what. I was hoping someone would be able to give me some insight as to how I could go about understanding it (to clarify: I’m still in the tenth grade - not a professional programmer by any means, and I’m not quite as well up on PHP as, say, Python, or C, but I’ve had no problem understanding the code itself - it’s the bigger picture I’m trying to get, a roadmap of sorts).


Hi @Positron11! Welcome to the farmOS community. :slight_smile:

Great question. We have some documentation about the overall architecture on farmOS.org, but it is lacking in detail, and hasn’t been updated to include some of the other pieces that have developed recently (farmOS-client, farmOS-map, farmOS.js, farmOS.py).

Nevertheless, you might find it useful: https://farmos.org/development/architecture/

Also, I recently posted an overview of the main farmOS projects over here: farmOS Projects and Issue Queues

The basic summary is: farmOS itself is a Drupal distribution, which means it is a server-side web application that runs on a web server. The codebase at https://github.com/farmOS/farmOS does not include the entire Drupal codebase - only the farmOS-specific portions of it that comprise the distribution. Drupal.org (as well as Drush) are used to build/package the full farmOS codebase, including Drupal. This is available for download as a tar.gz file on both https://drupal.org/project/farm and https://github.com/farmOS/farmOS/releases. To understand the organization of PHP code within farmOS, you’ll need to understand how modules are organized in Drupal. We follow Drupal coding standards closely and Drupal.org (and other online resources) provide great documentation for Drupal itself.

Recently, we also began work on a separate standalone application called farmOS Field Kit (repo: https://github.com/farmOS/farmOS-client). This is a JavaScript application that works offline, and is being packaged in a native Android and iOS applications. Because it is a JavaScript application, it can also be used as a PWA (progressive web app), which we currently have deployed at https://farmOS.app. This app communicates with a farmOS server via a RESTful API. More info: https://farmos.org/guide/app/

In addition to the server and client codebases, there are also JavaScript (available via npm) and Python (available via pip) libraries for communicating with a farmOS server via the API. The JavaScript library is used by farmOS-client, and the Python library is used by farmOS-aggregator.

There are a lot of aspects to farmOS! Some I haven’t mentioned here… but hopefully this provides an overview to start with, and perhaps prompt more questions as you start to dig in! :slight_smile:

1 Like

Thanks! I’ll let you know when I more questions.

@mstenta are there plans for any other API libs? I was looking at creating a lib in a different language for a personal development project that I would eventually want to contribute back if it works out but don’t want to go forward if there plans that would cause duplication.

1 Like

@applecreekacres There aren’t any official plans for other API libraries, but if you put something together and share it publicly, we can post a link to it from farmOS.org and other places!

1 Like

I am getting an API key missing error everytime I load one of the dashboard maps. I have the OpenStreetMap base layer option selected. Do I need an API key, and if so how likely am I to use more than $200 worth of requests?

1 Like

Sorry this is a known issue - basically Google Maps are being included even if you didn’t provide an API key. Here is the open bug report: https://www.drupal.org/project/farm/issues/3066192

I actually have this fixed in my branch that integrates the new farmOS-map library (see Starting work on farmOS-map library), but it’s not ready for use yet.

Do I need an API key, and if so how likely am I to use more than $200 worth of requests?

For an individual farm, I can almost guarantee that you will not exceed Google’s free tier limits for requests. Currently I’m sharing a single API key among all the hosted farmOS instances on Farmier, and I haven’t been charged anything yet. However, I was also grandfathered in from before they started charging, so I’m not sure if that’s a factor. Still - I think the free tier limits are probably a LOT more than an individual farm will ever use.

1 Like

Thanks for the info, cant wait to see the new library!

1 Like