The FixMyStreet platform’s directory structure
This page gives you an overview of where to find things in FixMyStreet's directories.
You’ll probably never need to worry about this if you’re just installing FixMyStreet – this is really more useful if you’re a developer planning on making more substantive changes to the code (and if you do, remember to read the page about feeding your changes back).
FixMyStreet uses Catalyst, which is a common Perl “Model-View-Controller” web framework. Again, you don’t need to be familiar with Catalyst to install or even work on the code, especially if all you’re doing is customising your installation.
Key directories and what they’re for
scripts for system tasks
For example, scripts used for installation or set-up, such as
make_css, and cron jobs (that is, those tasks that must be run at regular intervals, such as
mySociety's library of common functions
We maintain a common library that we use across many of our projects (not just FixMyStreet). This is implemented as a git submodule, so FixMyStreet contains it even though the code is separate. Normally, you don't need to think about this (because git handles it automatically)... but if you really do need to change anything here, be aware that it is a separate git repository.
The primary configuration file is
general.yml. This file isn't in the git repository (since it will contain information specific to your installation, including the database password), but example files are. See details of all configuration settings.
dbdirectory contains SQL for creating the tables and seeding some of the data — for example,
schema.sqlcontains the full database structure, and you use this when you first create the database (see 2. Create a new PostgreSQL database in the installation instructions if you're installing manually).
By convention, we also put "migration" SQL in here, so if the schema has changed since you installed and you need to add new fields, you'll find the individual changes you need to apply here.
local (as opposed to system-wide) Perl libraries
FixMyStreet installs its local CPAN modules here. These are populated by the script
The translation strings are stored in
.pofiles in directories specific to the locale and encoding. For example,
nn_NO.UTF-8/contains the translations for the Norwegian site. See more about translating FixMyStreet.
These are technical notes. This is in addition to the core documentation — which you are reading now — which is actually stored in the git repository in the
gh-pagesbranch, and published as GitHub pages.
the main application code
the Catalyst framework's own files — not FixMyStreet-specific
the core FixMyStreet Catalyst application
the core FixMyStreet program code
- Contains the Cobrand modules, which you can use if you need to add custom behaviour beyond that provided by config and template changes. See more abobut customising your site.
code for handling model data from the database
code for handling report sending
In addition to email and Open311, this is where the custom back-end integrations are found.
code for implementing FixMyStreet's Open311 functionality
fixmystreet_app_server.plfor running the Catalyst development server.
FixMyStreet's test suite runs under prove.
email and web templates
These are templates for the email messages that FixMyStreet sends, and the web pages it shows, in cobrand-specific directories. If no template can be found for a specific email or web page in the required cobrand, FixMyStreet uses the template in
default/. In this way, cobrands only need to override templates that differ from FixMyStreet's default — it's feasible for your cobrand's template directories to be empty. See more abobut customising your site.
Template files for the email messages that FixMyStreet sends, as
Template files for the web pages. The templates, which all have the extension
.html, use the popular Template Toolkit system.
FixMyStreet stores compiled templates, created on demand with the extension
.ttc, alongside the template files. Don't edit these files: edit the
.htmlones, and FixMyStreet will overwrite the
resources specific to cobrands
For example, if your installation has its own logo, put it here.
some core SCSS definitions
Images, including navigation icons and sprites, used by the default site (and hence available to other cobrands too) — for example
pin-green.pngis the green pin used on most cobrand's maps.
We’ve missed out some of the less important subdirectories here just to keep things clear.