PlaceCal

Introduction

PlaceCal is an online calendar which lists events and activities by and for members of local communities, curated around interests and locality.

To get an idea of the project and what we're about, check out the handbook.

Requirements

To run PlaceCal locally you will need to install the following dependencies:

• Docker (for PostgreSQL)
• Ruby (see .ruby-version for exact version)
• Node.js (see .node-version) & (optional) nvm to manage it
• Yarn 1.x
• ImageMagick for image manipulation
• Graphviz for documentation diagrams
• Chrome/Chromium for system tests along with a matching version of Chromedriver

Quickstart

Set up PostgreSQL with docker

If you don't already have PostgreSQL installed and running, set it up with docker:

make docker

To tear down the docker setup, run make clean.

Run the setup script

bin/setup

This will install dependencies, create the database, and seed it with development data.

• Login: root@placecal.org / password

See SEEDS.md for full details on what gets created (users, sites, partners, events).

Run the thing

• Start the server with bin/dev
• Make sure you use lvh.me:3000 instead of localhost:3000 or you will have authentication problems
• The admin interface is at admin.lvh.me:3000
• Access code docs through your local filesystem and update them with bin/rails yard

Quickstart with docker for GFSC devs

Make sure all of the above dependencies are installed (and ask someone to add your public ssh key to the servers if you are staff).

Then make sure the docker daemon is running, and run

make setup_with_docker

Local site is now running at lvh.me:3000

Some other useful commands for developing can be found in the makefile.

Troubleshooting

If the make command fails and you can't work out why, here are some suggestions:

• Do you have an older version of the database hanging around? Try running rails db:drop:all
• Is the docker daemon running?
• Is the port in use by another application or docker container? Try stopping or removing any conflicting containers
• Are you using the correct node version? Try running nvm use

Importing calendars

To import all events, run the following command.

rails events:import_all_calendars

After this has run once, the following command can be run which attempts to skip calendars which have not been updated. This should be run regularly on a cron in production environments. See INSTALL.md for cron setup on the server.

rails events:scan_for_calendars_needing_import

To import one calendar, run:

rails events:import_calendar[100]

# nb: zsh users will need to escape brackets
rails events:import_calendar\[100\]

Testing, linting and formatting

PlaceCal uses RSpec for unit/integration tests and Cucumber for BDD-style acceptance tests. We use Rubocop to lint our Ruby code.

We use Prettier to format everything it's able to parse. We run this automatically as part of a pre-commit hook.

Note: Tests require a running PostgreSQL database. If using Docker, ensure make docker is running first.

Running tests

# All tests with linting
make test

# Fast unit tests only (excludes system specs)
bin/test --unit --no-lint

# System tests (browser-based, requires Chrome)
bin/test --system --no-lint

# Cucumber features
bin/test --cucumber --no-lint

# Direct commands
bundle exec rspec                        # Fast specs only
RUN_SLOW_TESTS=true bundle exec rspec    # Include system specs
bundle exec cucumber                     # Cucumber features

Documentation

Further documentation for PlaceCal is in the PlaceCal Handbook.

The developer Procfile will load a yard language server, this is visible at http://localhost:8808.

If you are working with the code and are completely lost you can also try the GFSC discord server where you can prod a human for answers.

Folder structure

── app
│   ├── assets
│   │   ├── builds              # Bundled JavaScript
│   │   ├── config              # Specifies assets to be compiled
│   │   ├── fonts
│   │   ├── images
│   │   └── stylesheets
│   ├── components              # Phlex components for reusable UI elements
│   │   └── admin               # Admin-specific components (forms, cards, etc.)
│   ├── constraints             # Directs to correct site based on subdomain
│   ├── controllers             # Public app controllers
│   │   ├── admin               # Admin area controllers
│   │   ├── concerns
│   │   └── users
│   ├── datatables              # Admin area datatables
│   ├── graphql                 # API
│   ├── helpers
│   ├── javascript              # Source JavaScript (importmap-rails, no build step)
│   │   └── controllers         # Stimulus controllers
│   │       └── mixins          # Shared Stimulus controller mixins
│   ├── jobs                    # Importer logic - jobs are created by cron (`/lib/tasks`). There's a readme here with more info
│   ├── mailers                 # Email configuration
│   ├── models
│   ├── policies                # Pundit rules for who can do and access what
│   ├── queries                 # Query objects for complex database queries
│   ├── tailwind                # Tailwind CSS source files (admin interface)
│   ├── uploaders               # CarrierWave rules for handling image and logo uploads
│   ├── validators              # Custom validators (e.g. postcode)
│   └── views
│       ├── admin               # Admin area
│       ├── collections         # Deprecated feature to create arbitrary event collections
│       ├── devise              # Authentication
│       ├── events              # Event indexes and show page
│       ├── join_mailer         # Templates for creating accounts
│       ├── joins               # "Join PlaceCal" form page
│       ├── layouts             # Page templates
│       ├── moderation_mailer   # Templates for when partners get moderated
│       ├── news                # News article templates - half implemented
│       ├── pages               # Static pages mostly used on homepage
│       ├── partners            # Partner indexes and show pages
│       ├── shared              # Shared partials
│       └── sites               # Site homepages e.g. mysite.placecal.org
├── collections                 # API examples to be loaded with Bruno
├── config
│   ├── environments
│   ├── initializers
│   ├── locales
│   └── robots
├── db
│   ├── images                  # Some seed images
│   │   ├── sites
│   │   └── supporters
│   ├── migrate
│   └── seeds                   # Seeds using Normal Island data for development
├── doc                         # Documentation including testing guides and ADRs
│   ├── adr                     # Architectural decision records
│   └── ai                      # Optional AI coding assistant configuration
├── features                    # Cucumber BDD features
│   ├── step_definitions        # Step implementations
│   └── support                 # Cucumber environment setup
├── lib
│   ├── assets
│   ├── data                    # UK geography ward to district data used to create neighbourhood info
│   ├── normal_island           # Fictional geography data for tests and seeds
│   ├── tasks                   # Rake tasks that create ActiveJobs
│   └── templates
│       └── erb                 # Rails scaffold templates
├── log
├── config/deploy.yml           # Kamal deployment configuration
├── public
├── .kamal                      # Kamal secrets configuration
├── spec                        # RSpec test suite
│   ├── components              # Phlex component specs
│   ├── datatables              # Datatable specs
│   ├── factories               # FactoryBot factories using Normal Island data
│   │   └── normal_island       # Normal Island-specific factories
│   ├── fixtures
│   │   └── vcr_cassettes       # Recorded API responses for testing
│   ├── helpers                 # Helper specs
│   ├── jobs                    # Background job specs (calendar importers)
│   ├── mailers                 # Mailer specs
│   ├── models                  # Model specs
│   ├── policies                # Pundit policy specs
│   ├── queries                 # Query object specs
│   ├── requests                # Request specs (controllers, GraphQL)
│   │   ├── admin
│   │   ├── graphql
│   │   └── public
│   ├── support                 # Test helpers, shared contexts/examples
│   └── system                  # Capybara system specs (requires Chrome)
│       └── admin

API

API examples and test environment are provided using Bruno.

Install it with your system package manager then point it at the collections directory.

AI Coding Assistants (Optional)

PlaceCal includes optional support for AI coding assistants. We're tool-agnostic and have structured the project to work with various AI assistants.

Note: This is a legacy codebase with significant tech debt. AI assistants can help navigate and improve it, but expect some rough edges.

Setup

bin/setup-ai

This enables the optional :ai gem group and installs dependencies.

What's Included

• AGENTS.md - Context file for AI assistants
• doc/ai/ - Agent configuration and prompts
• agents-swarm.yml - Multi-agent swarm configuration

Using with Different Tools

The configuration is designed to be adaptable:

• Claude Code / Cursor: Uses AGENTS.md for context automatically
• Other assistants: Point them at AGENTS.md and doc/ai/context.md
• Swarm-based tools: Use agents-swarm.yml for multi-agent setups

Disabling

bundle config unset --local with
bundle install

Donations

If you'd like to support development, please consider supporting GFSC.