Architecture
This page outlines the general architecture and design principles of the Permit Connect Navigator Service (PCNS). It is mainly intended for a technical audience, and for people who want to have a better understanding of how the system works.
Figure 1 – The general infrastructure and network topology of PCNS
We receive data from an external service Common Hosted Forms Service (CHEFS) and from our PCNS client written in VueJs, managed by our PCNS NodeJs application. File upload/download is managed by the external service Common Object Management Service (COMS). The NodeJs application interfaces with our PCNS Postgres database.
The PostgreSQL database is written and handled via managed, code-first migrations. We generally store tables containing activities, initiatives, enquiries, permits, submissions, users, and how they relate to each other.
PCNS is a has a mono-repository architecture containing both a frontend and backend. The following figures depict the database schema structure as of July 2024.
Figure 2 – The public schema for a PCNS database
The database tracks activities, initiatives, enquiries, permits, submissions, users, and a few other tables and how they relate to each other. We enforce foreign key integrity by invoking onUpdate and onDelete cascades in Postgres. This ensures that we do not have dangling references when entries are removed from the system.
Figure 3 – The audit schema for a PCNS database
We use a generic audit schema table to track any update and delete operations done on the database. This table is only modified by database via table triggers, and is not accessible by the PCNS application itself. This meets most general security, tracking and auditing requirements.
The code structure in PCNS follows a simple, layered structure following best practice recommendations from Express, Node, ES6, and Typescript coding styles and utilize Eslint and Prettier to enforce those recommendations.
The backend is an ExpressJs application managing a PostgresDB. We utilize the KnexJs package for database migration management and configuration and PrismaJs for database object-relation management.
The codebase has the following discrete layers:
| Layer | Purpose |
|---|---|
| Controller | Contains controller express logic for determining what services to invoke and in what order |
| DB | Contains the direct database table model definitions and typical modification queries |
| Middleware | Contains middleware functions for handling authentication, authorization and feature toggles |
| Routes | Contains defined Express routes for defining the PCNS API shape and invokes controllers |
| Services | Contains logic for interacting with the Database, COMS API, or other external APIs for specific tasks |
| Validators | Contains logic which examines and enforces incoming request shapes and patterns |
Each layer is designed to focus on one specific aspect of business logic. Calls between layers are designed to be deliberate, scoped, and contained. This makes it easier to tell what each piece of code is doing and what it depends on. For example, the validation layer sits between the routes and controllers. It ensures that incoming network calls are properly formatted before proceeding with execution.
Middleware
PCNS middleware focuses on ensuring that the appropriate business logic filters are applied as early as possible. Concerns such as feature toggles, authentication and authorization are handled here. Express executes middleware in the order of introduction. It will sequentially execute and then invoke the next callback as a part of its call stack. Because of this, we must ensure that the order we introduce and execute our middleware adhere to the following pattern:
- Validation and structural checks
- Permission and authorization checks
- Any remaining middleware hooks before invoking the controller
The frontend utilizes the VueJs framework to build the user interface, using Typescript. We utilize several library packages with this framework that shape the structure of our frontend.
The following is a partial list of important packages used in the frontend:
| Package | Purpose |
|---|---|
| Axios | Library for making HTTP requests |
| Pinia | State management framework for VueJs |
| Primevue | Vue component and template library |
| Vite | Javascript bundler, hot-module replacement capabilities |
| Vitest | Javascript unit testing framework |
| Vue-router | Client-side routing library for VueJs |
| Vue-test-utils | VueJs unit test utility library |