StreetSign Developer Documentation

This will contain the documentation for developers, either working on StreetSign, or making plugins/other software to work with it.

It’s assumed that you’re reasonably familiar with StreetSign the end user web interface and basic terminology (Post, Feed, Screen, Zone, etc). If not, see the Getting Started

Project Structure Overview

The main “everything” is kept in the folder (& python package) "streetsign_server", which is a WSGI application, and can be treated as such. Within streetsign_server:

__init__.py

The basic app definition, which pulls in everything else that it needs, calls models.init(), and imports all view modules.

models/

The ORM database models live in a package with several submodules:

  • base.py — DB connection, utility functions, base model class, custom exceptions

  • users.py — User, Group, UserGroup classes

  • auth.py — UserSession, login/logout/get_current_user functions

  • feeds.py — Feed, FeedPermission, Post, ExternalSource classes

  • screens.py — Screen class

  • config.py — ConfigVar key-value store

Full Reference: streetsign_server.models

user_session.py

A bunch of helpful functions for dealing with the user session & authentication stuff. The basics are kept in the User, Group, and UserSession objects defined in models/, but the functions here help make life easier and shorter. The function login(username, password) for example, attempts to log in with those credentials, and if it can, then it creates the appropriate UserSession database items, and adds useful items to the session cookie.

Full Reference: streetsign_server.user_session

views/

The views package contains all of the actual “endpoints” of the web application. So the functions which generate the pages you see when you use the web interface, the screen rendering, etc. It is mostly split out into submodules.

Full Reference: streetsign_server.views

logic/

The logic package is where more complex logic is being moved to from the views package. Once things start becoming more complex than simply pulling things from the database and rendering it, and the logic is application specific rather than model specific, then it should go in here. There is more logic than really should be in views/, and in general, it should be ported across to here.

Full Reference: streetsign_server.logic

static/

The standard Flask static assets folder.

static/lib/

Contains external libraries (jQuery, Alpine.js, Bootstrap 5, Choices.js, Quill, Flatpickr, Day.js, Prism, Bootstrap Icons).

static/screens/

Is for all the css & javascript used by the front end screen rendering.

static/user_files/

Is the default location for uploaded user files. This can be configured to some degree in the root of the tree config.py.

static/style.css

As much as possible, I’ve kept with vanilla twitter bootstrap, as it looks perfectly good enough. Anything application specific is in here. Of course, this is talking only about the web interface, not about the output screen rendering, which doesn’t reference this file at all.

static/main.js

All the basic functions which all of the back end needs. Such as rendering “flashed” notices, etc.

static/model_zones.js

The screen editor is a reasonably complex beast, and uses the Alpine.js library to keep everything sane. This file contains the zones model and functions to control it all (creating the preview, etc). This file is not used at all in the output screen rendering. It’s a totally separate kettle of fish.

static/post_times_editor.js

The post time restrictions editing is also a bit fiddly, so all the clobber for that is kept in here.

static/post_editor.js

JavaScript for the post editing interface.

static/alias_editor.js

JavaScript for managing client screen aliases.

Other files in the root directory

Starting with the file layout:

run.py - run the basic development web server, Waitress stand alone

WSGI server, or with Werkzeug profiler. The development server’s interactive debugger is off by default (opt in with FLASK_DEBUG=1, which also restricts the bind to 127.0.0.1).

setup.sh - downloads all needed python packages, including virtualenv,

and installs them into a local virtualenv called, very creatively, .virtualenv. Also initialises the database, if it doesn’t exist. If you totally stuff up the database, then you can simply delete it and run this script again. (Now delegates to the Makefile.)

database.db - the sqlite database, generated by setup.sh, normally.

db.py - database management script (initial creation and migrations).

Dockerfile - multi-stage Docker build producing a ~45 MB production image.

API/Urls

Can be found in API/Urls

How Post Types work

Full Reference: streetsign_server.post_types

How External Data Types Work

Full Reference: streetsign_server.external_source_types

How the ‘Screens’ Work

Full Reference: Screen Design

How Different Libraries are used

Full Reference: External Libraries