Digital Planning Register
Screenshot of the planning register frontend
This repository contains the backend code for the Digital Planning Register (DPR) project. The DPR is a system for indexing and viewing public planning applications in the Post-submission published application format. The data is sourced from local authorities' ODP compliant APIs, indexed, and made available via a public API and web interface.
- You can view the live site at planningregister.org.
- To read more about the schema, see the digital-planning-data-schemas repository.
This project was created using bun init in bun v1.2.19. Bun is a fast all-in-one JavaScript runtime.
Technologies used:
- Bun - JavaScript runtime
- TypeScript - Type checking
- Elysia - TypeScript with End-to-End Type Safety, type integrity, and exceptional developer experience. Supercharged by Bun.
- TypeBox - A Runtime Type System for JavaScript
- Open API - API specification
- JSON schema - JSON schema standard
- React - Frontend library
- Next.js - React framework
- picocss - CSS framework
- GovUK Frontend - Design system for public sector services
- Storybook - UI component development environment
- Drizzle ORM - Type-safe SQL ORM
- PostgreSQL - Database
- Docker - Containerization
- ESLint - Linting
- Prettier - Code formatting
- Husky - Git hooks
- GitHub Actions - CI/CD
This repository is a monorepo. The structure is as follows:
Contains applications, client and server, such as the api and the admin interface for managing the dpr
@dpr/admin- The administration interface for the Digital Planning Register@dpr/api- The application programming interface (API) for the Digital Planning Register
Contains methods and functions used to convert different payloads into ODP format
@dpr/converter-bops- A utility module for converting data from the Back Office Planning System (BOPS) API to the ODP Post-submission format.
Contains methods and functions used to handle incoming requests and responses
@dpr/handler-bops- An elysia plugin for handling requests and responses from the Back Office Planning System (BOPS) API.
Contains shared libraries used across applications
@dpr/application-generator- Generates dummy application data in Post-submission format for testing and development purposes@dpr/config- Configuration management for the packages in this monorepo@dpr/dev-config- Development configuration for the packages in this monorepo, included eslint and base typescript configurations@dpr/libs- A shared library of common utilities to reduce code duplication and consolidate dependencies across packages.@dpr/odp-schemas- The post submission schema in typebox form - eventually this will be replaced by thedigital-planning-data-schemaspackage@dpr/ui- Contains react components, styles and a storybook for the Digital Planning Register that comply with Post-submission schema. Eventually all DPR components will come from here
Note
Packages in here are not included in the bun run script and will need to be run manually with bun run workspace
A general purpose space for testing things out. A space to experiment with new ideas, packages, or technologies without affecting the main applications.
You will need to have Bun and Docker installed.
Tip
Make sure you have the latest version of Bun by running bun upgrade.
To install dependencies, run:
bun installTo run the whole stack, use the following command:
docker compose up -d
bun run dev
bun run seedYou can then view the API at http://localhost:4000, the admin interface at http://localhost:3000, and Storybook at http://localhost:6006.
This repository has two helper scripts in the scripts directory:
run- A script to run commands in the entire monorepoworkspace- A script to run commands in a specific package
There are standard commands in place across all packages. To use these scripts, you can run bun run <command> from the root of the repository and it will run the command in all packages that have that command defined in their package.json.
For example you can run the tests in all packages using:
bun run testThese scripts are required in every package's package.json:
Note
eslint isn't fully set up yet so the commands may change, or in the case of nextjs applications it may already have its own linting command
{
"scripts": {
"typecheck": "tsc --noEmit",
"typeconfig": "tsc --showConfig",
"lint": "eslint .",
"format": "eslint . --fix"
}
}typecheck: Type-check the codebasetypeconfig: Show the TypeScript configuration (useful for debugging)lint: Lint the codebase using ESLintformat: Format the codebase using ESLint with the--fixoption
In addition, the following commands are used to setup the package's development environment:
{
"scripts": {
"dev": "bun run --hot src/server.ts",
"seed": "bun run scripts/seed.ts"
}
}dev: Starts the development serverseed: Seeds the package with any initial data
The following commands are used to run tests:
{
"scripts": {
"test": "bun test",
"test:unit": "bun test --filter 'unit'",
"test:e2e": "bun test --filter 'e2e'",
"coverage": "bun test --coverage"
}
}test: Runs all tests, iftest:unitandtest:e2eare defined, it should run bothtest:unit: Runs unit tests onlytest:e2e: Runs end-to-end tests onlycoverage: Generates a test coverage report
For production builds and running the package in production mode, the following commands are used:
{
"scripts": {
"build": "NODE_ENV=production bun build src/server.ts --outdir=dist --target=esnext",
"start": "NODE_ENV=production bun dist/server.js",
"serve": "bun run build && bun run start"
}
}build: Builds the package for productionstart: Starts the package in production mode by directly executing the main entry point.serve: Combinesbuildandstartinto a single command for convenience
The following commands are used to create a production Docker image:
{
"scripts": {
"docker": "cd ../.. && docker build -t dpr-backend:<package-name> -f ./apps/<package-name>/Dockerfile ."
}
}docker: Builds a Docker image for the package, replacing<package-name>with the actual name of the package
The following commands are optional utility scripts that can be included as needed:
{
"scripts": {
"clean": "bun run scripts/clean.ts"
}
}clean: Cleans up any build artifacts or temporary files
To work within individual packages, you can use the bun workspace command. For example, to run the dev server for the API and Admin packages, run:
bun workspace @dpr/api bun run dev
bun workspace @dpr/admin bun run devTip
The bun workspace command allows you to run commands within a specific package in the monorepo without cding into its directory.
When creating a new package you will need to ensure that the standard commands are included in the package.json of the new package.
{
"name": "@dpr/<package-name>",
"description": "<package-description>",
"version": "0.0.0",
"private": true,
"type": "module",
"scripts": {
"typecheck": "tsc --noEmit",
"typeconfig": "tsc --showConfig",
"lint": "eslint .",
"format": "eslint . --fix",
"dev": "bun run --hot src/server.ts",
"seed": "bun run scripts/seed.ts",
"test": "bun test",
"test:unit": "bun test --filter 'unit'",
"test:e2e": "bun test --filter 'e2e'",
"coverage": "bun test --coverage",
"build": "NODE_ENV=production bun build src/server.ts --outdir=dist --target=esnext",
"start": "NODE_ENV=production bun dist/server.js",
"serve": "bun run build && bun run start",
"docker": "cd ../.. && docker build -t dpr-backend:<package-name> -f ./apps/<package-name>/Dockerfile .",
"clean": "bun run scripts/clean.ts"
},
"dependencies": {},
"devDependencies": {
"@dpr/dev-config": "catalog:",
"typescript": "catalog:"
}
}If you are using any bun commands in your package you will need to install the @types/bun package as a dev dependency. See Bun docs for more details.
bun add -d @types/bun # dev dependencyIf you are using the Post-submission schema in your package you should use the digital-planning-data-schemas package. Add the following to your dependencies:
{
"digital-planning-data-schemas": "file:../../digital-planning-data-schemas-0.7.5.tgz"
}The @dpr/odp-schemas package is a temporary measure until the digital-planning-data-schemas package contains typebox types.
{
"@dpr/odp-schemas": "workspace:*"
}Details about each package, its purpose, and how to work with it.
The administration interface for the Digital Planning Register
bun run workspace @dpr/admin bun run db:studio
bunx drizzle-kit generate --custom --name=seed-clientsThe application programming interface (API) for the Digital Planning Register
A utility module for converting data from the Back Office Planning System (BOPS) API to the ODP Post-submission format.
An elysia plugin for handling requests and responses from the Back Office Planning System (BOPS) API.
Generates dummy application data in Post-submission format for testing and development purposes
Development configuration management for the packages in this monorepo, included eslint and base typescript configurations
Configuration management for the packages in this monorepo
A shared library of common utilities to reduce code duplication and consolidate dependencies across packages.
The post submission schema in typebox form - eventually this will be replaced by the digital-planning-data-schemas package
Contains react components, styles and a storybook for the Digital Planning Register that comply with Post-submission schema. Eventually all DPR components will come from here
@TODO
Each package has its own .env.local file for local development. You can create these files by copying the .env.example files in each package and filling in the required values.
Note
Note: When NODE_ENV=test, .env.local is not loaded. See Bun docs for more details.
Note
The database is not currently being used in production but will be in the future
Currently the database is managed using Drizzle ORM.
If you want to make changes to the client table in the database, for example adding a new column, follow the instructions below:
Make changes to the clients pgTable in apps/admin/src/db/client.ts. Run the following commands:
-
bun workspace @dpr/admin bunx drizzle-kit generateThis will generate a new migration file in
apps/admin/migrations -
bun workspace @dpr/admin bunx drizzle-kit migrateThis will apply the new migration to the database table
@TODO
# elide-lines needed for now https://github.com/oven-sh/bun/issues/17918
bun run --elide-lines 0 --filter='@apps/dpr-api' config
# or https://bun.com/docs/runtime/bunfig#bun-run
bun run --filter='@apps/dpr-api' -c=bunfig.toml config
# or use our script
bun workspace @dpr/api bun run configTo debug docker builds you can run:
docker compose build --progress=plain --no-cacheCurrently apps/api uses
{
"target": "esnext",
"module": "preserve",
"moduleResolution": "bundler"
}but if we get any issues (unlikely) we can switch to
{
"target": "es2021",
"module": "es2022",
"moduleResolution": "node10"
}If your question or issue relates to the Post-submission schema please raise it in the digital-planning-data-schemas repository.
If your question or issue relates to the MHCLG schema(s) please raise it in one of the following repositories:
- Designing planning and housing data that works for everyone
- repository: planning-data-design
- website: design.planning.data.gov.uk
- Planning application submissions project
The DPR is happy to accept community contribution. Please ensure you submit an issue before submitting a pull request. We prefer open community discussion before accepting new features. If your contribution or issue relates to the schema please raise it in the digital-planning-data-schemas repository.
License information.