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

bin

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 send-reports).

commonlib

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.

conf

configuration files

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.

data

data files

db

database SQL

The db directory contains SQL for creating the tables and seeding some of the data — for example, schema.sql contains 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

local (as opposed to system-wide) Perl libraries

FixMyStreet installs its local CPAN modules here. These are populated by the script bin/install_perl_modules.

locale

translations (internationalisation/i18n)

The translation strings are stored in .po files 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.

notes

documentation notes

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 docs directory, and published as GitHub pages.

perllib

the main application code

Catalyst

the Catalyst framework's own files — not FixMyStreet-specific

DBIx

database bindings

FixMyStreet

the core FixMyStreet Catalyst application

App

the core FixMyStreet program code

Controller

Model

View

Cobrand

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.

DB

code for handling model data from the database

Result

ResultSet

GeoCode

Map

Roles

SendReport

code for handling report sending

In addition to email and Open311, this is where the custom back-end integrations are found.

Geo

Open311

code for implementing FixMyStreet's Open311 functionality

script

Catalyst scripts

For example, fixmystreet_app_server.pl for running the Catalyst development server.

t

tests

FixMyStreet's test suite runs under prove.

templates

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.

email

Template files for the email messages that FixMyStreet sends, as .txt text files.

web

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 .html ones, and FixMyStreet will overwrite the .ttc files automatically.

web

static resources for the web pages, including stylesheets, javascript, images

cobrands

resources specific to cobrands

For example, if your installation has its own logo, put it here.

css

some core SCSS definitions

i

images

Images, including navigation icons and sprites, used by the default site (and hence available to other cobrands too) — for example pin-green.png is the green pin used on most cobrand's maps.

iphone

js

JavaScript files

posters

We’ve missed out some of the less important subdirectories here just to keep things clear.