The Big Tour

Here we try to give a "full tour" of the Rattail Project in one page. It's intentionally brief in many areas but plenty wordy (and technical) still; it aims to at least touch on "all" the birds-eye-view details.

Really this page tries to answer the question for the reader - who is assumed to be a developer or sysadmin! - "Should I even be interested in Rattail?" By the time you've read this page you should have the answer to that.

In a nutshell, Rattail tries to offer a "basic and unobtrusive, yet opinionated and convenient" Swiss Army Knife / toolkit for building custom back-end / automation software for integrating with other systems and interacting with that data. Retailers were the assumed market for this software but in practice it can be used for many other purposes / organizations as well.

To some extent each of the primary aspects of the Rattail Project (below) can be used independently, so feel free to start wherever you like in practice.

Remember, the word "Poser" here really means "Custom Project" - i.e. your custom project - so replace that name mentally with whatever you like, i.e. whatever you want to name your custom project.

Database

It often is useful to maintain one or more Poser databases, to facilitate automation or other organization-defined workflow. Note that the web app requires a database.

Schema Definition

Rattail provides a "core" ("common") database schema, with tables for users, products, customers, etc. Each custom Poser app is free to define "extensions" to this schema, to track things not represented by the core schema. (It's generally expected that most Poser apps would do so.) These schema definitions are made using the SQLAlchemy ORM library/syntax.

Note that whereas you can pick and choose which parts of Rattail software you want to run, the schema is "all or nothing" - meaning each DB built using the Rattail framework will effectively contain this full "core + extensions" schema. In practice that's no big deal - just ignore any tables you don't need within app logic, as the core schema is sure to define some you don't need!

Location / Purpose

The assumption is that generally each Poser app will require one such database, which will live in PostgreSQL. At the very least, this DB would be needed to store user accounts and roles/permissions for the Poser web app, if that is deployed. Beyond that, it's often useful to treat this DB as a "pseudo-authority" - meaning, with the right setup you can expect this DB to always contain the "latest" authoritative data (assuming datasync etc.) in which case you can then develop further reports and app features based on this "custom but very accurate" DB. Additionally it can be useful to treat this DB as a "workspace" for moving data between other systems but with extra processing / validation steps etc.

In some cases (e.g. minimal integration) no such database is needed; in other cases (e.g. multi-store) there may be multiple Poser apps with each requiring its own database.

Schema Upgrades

Regardless of how many Poser databases must exist, they should generally be kept up-to-date such that the schema of each is the same. Among other reasons, this is because the datasync daemon will usually try to sync all fields for a record, in which case those field definitions must match between app nodes. Alembic is the tool used to track migrations and keep schema for each database upgraded.

Data

As for how data makes its way into this database, that will vary of course but by and large will be via "integration" (with other systems) and/or "web app" (aka. integrating with users) - both of which are discussed further below.

Note that if there are multiple Poser databases, then often a new data change in one node, will be propagated to all other nodes, typically by way of a "host" (master) node. When applicable, this would be handled via datasync.

Integrations

TODO

Web App

TODO

Config Management

TODO