ServPulse/Development guide

Getting started

git clone https://devcentral.nasqueron.org/source/servpulse.git
cd servpulse
cp .env.example .env
docker compose up

The application will be available at:

• Status page: http://localhost:8080
• API: http://localhost:3000/api

Tip: if you're maintainer of the project and need write access to the repository, you need to clone by SSH: git clone ssh://vcs@devcentral.nasqueron.org:5022/source/servpulse.git. If you've already cloned the repository, you can edit the URL in .git/config.

Project structure

servpulse/
├── backend/          Express.js API server (MVC pattern)
│   ├── controllers/  Request handlers
│   ├── models/       Data access layer (raw pg queries)
│   ├── routes/       API route definitions
│   ├── middleware/    JWT authentication
│   ├── services/     Business logic (notifications, health checks)
│   ├── config/       App config (app.json) and database connection
│   └── __tests__/    Jest unit tests
├── frontend/         Vue.js 3 application
│   └── src/
│       ├── components/   Reusable UI components
│       ├── composables/  Vue 3 composables (useServices, useIncidents, etc.)
│       ├── views/        Page views (StatusPage, AdminDashboard, AdminLogin)
│       ├── plugins/      API client (Axios)
│       ├── utils/        Status helpers and formatters
│       └── router/       Vue Router config with auth guards
├── database/         SQL schema (init.sql)
└── docker-compose.yml

Code conventions

• Nasqueron conventions
• Single quotes for strings
• camelCase for variables and functions
• Vue 3 Composition API (<script setup>) for components
• Tailwind CSS utility classes for styling (no scoped styles)
• Raw pg queries in models (no ORM)

How to add a new feature

Adding a backend resource

1. Add table to database/init.sql
2. Create models/resourceModel.js — raw pg queries
3. Create controllers/resourceController.js — req/res handlers
4. Create routes/resourceRoutes.js — Express router with auth where needed
5. Register routes in app.js
6. Add tests in __tests__/controllers/resourceController.test.js

Adding a frontend component

1. Create .vue file in src/components/ using <script setup>
2. Use Tailwind classes and existing utilities from @/utils/status
3. Import composables from @/composables/ for data
4. Add tests in src/components/__tests__/

Axios integration

The API client is configured in frontend/src/plugins/api.js. It uses Axios with a base URL from VITE_API_URL and automatically attaches JWT tokens from localStorage via a request interceptor.

Composables (useServices, useIncidents, etc.) wrap the API calls and return reactive refs:

const { services, loading, error, fetchServices } = useServices()

Testing

# Backend (Jest)
cd backend && npm test

# Frontend (Vitest)
cd frontend && npm run test:unit

Git workflow

See docs/workflow.md in the repository for the arc diff workflow.