Nasqueron Agora - User contributions [en]

ServPulse/User stories

2026-02-17T15:45:47Z

Ieli:

'''User stories''' allow us to define site features.

== Persona ==

Created during 2023-06-02 meeting with Eli, DorianWinty, Dereckson and Fauve.

<gallery>
File:ServPulse user stories - Persona - Nasqueron member.png|Persona 1 - Nasqueron member
File:ServPulse user stories - Persona - Nasqueron ops.png|Persona 2 - Nasqueron ops
File:ServPulse user stories - Persona - Visitor.png|Persona 3 - Visitor
</gallery>

== User stories ==

=== Katherina, the student (Nasqueron member) ===

Katherina is interested in open source and free culture. She has a background in computing but is more into development than operations. She uses Ubuntu but isn't comfortable with the terminal. She wants to use Nasqueron services without worrying about infrastructure.

''Pain points: "Why DevCentral doesn't answer?", "I'd like to connect to IRC but Eglide doesn't ping", "Sometimes it's complicated to know what services we have or on what servers."''

* As a member, I want to see at a glance if all services are fine or if something is broken, so I don't have to guess why a service isn't responding.
* As a member, I want to see which specific service is affected and what its current status is, so I know whether the problem is with DevCentral, IRC, or something else.
* As a member, I want to see what is being done about an ongoing incident, so I know the team is aware and working on it.
* As a member, I want to subscribe to email notifications, so I'm informed of incidents without having to check the page.
* As a member, I want to see services organized by group, so I can find the service I care about without knowing the infrastructure details.
* As a member, I want to see past incidents and how they were resolved, so I can understand what happened while I was away.
* As a member, I want the page to update automatically, so I don't have to keep refreshing during an incident.

=== Gourou, the tech-savvy (Nasqueron ops) ===

Gourou knows the Nasqueron infrastructure well. He prefers command-line tools and simple UIs over complex interfaces. He could use either a GUI or a TUI. He wants to manage services easily and detect intermittent downtime.

''Pain points: "Does all my infrastructure is going well?", "Do we have some intermittent down time?", "Does it's easy to use?"''

* As an ops member, I want to manage services (create, edit, delete) from an admin dashboard, so I don't need direct database access.
* As an ops member, I want to create incidents and update their status through a lifecycle (investigating → identified → monitoring → resolved), so I can communicate the resolution process.
* As an ops member, I want to schedule maintenance windows, so visitors are informed in advance.
* As an ops member, I want monitoring tools to automatically update service status via a webhook, so the page reflects reality without manual action.
* As an ops member, I want to see historical uptime statistics per service, so I can detect intermittent downtime patterns.
* As an ops member, I want health checks to run automatically against service URLs, so statuses stay current without manual updates.
* As an ops member, I want health checks to distinguish between degraded performance and full outage, so the status page is more accurate.
* As an ops member, I want to generate an admin token via CLI, so I can access the dashboard without a user/password system.
* As an ops member, I want to link incidents and maintenance to affected services, so visitors see which services are impacted.
* As an ops member, I want to customize the page title, navigation links, and footer, so the status page matches our branding.
* As an ops member, I want to deploy the entire application with a single command, so setup is fast and repeatable.

=== Mykel, the artist and writer (Visitor) ===

Mykel identifies as they, is in their 30s, and uses Nasqueron services casually — clicking links, reading wikis, browsing. They are UI-oriented and put off by complexity, too much text, or too much theory. They interact with Nasqueron services randomly and without commitment.

''Pain points: "I've just clicked on a link, got an error who told me to check status", "Complexity?", "Too much text."''

* As a visitor, I want to see an overall status banner immediately, so I know in one second if systems are healthy or not.
* As a visitor, I want the page to be simple and visual (not walls of text), so I can understand the situation at a glance.
* As a visitor, I want to see which specific service is down, so I know if the one I care about is affected.
* As a visitor, I want to subscribe to notifications, so I know when the service I use is back without checking repeatedly.
* As a visitor, I want a clear page when I land on a broken link, so I'm not confused by a blank screen.
* As a visitor, I want the page to work well on mobile, so I can check status from my phone.
* As a visitor, I want dark mode support, so the page is comfortable to read at night.

ServPulse/Domain

2026-02-17T15:37:45Z

Ieli:

== Lexicon ==

;Configuration
:Application-level settings stored in config/app.json and served via the config API.
:'''Attributes:''' navbar.title, navbar.buttons_left (array of {name, link}), footer.line1 (text with %link1%/%link2% placeholders, labels, URLs), footer.line2 (text with %link% placeholder, label, URL).
:'''Endpoint:''' GET /api/config/getAll (public), PUT /api/config (admin)

;Service
:A monitored entity on the status page (server, application, database, API, etc.). Services can be grouped and ordered.
:'''Attributes:''' name, group, description, url, auto_status, status (operational, degraded, partial, major, maintenance), order.
:'''Database table:''' service

;Metric
:Performance data recorded per service, either by the health check service (automatic) or via the API (manual).
:'''Attributes:''' service_id, uptime (decimal 0-100), response_time (integer, ms), error_rate (decimal 0-100), recorded_at.
:'''Database table:''' metric (indexed on service_id + recorded_at)
:'''Endpoint:''' GET /api/metrics (latest per service), GET /api/metrics/service/:id?days=30 (raw), GET /api/metrics/service/:id/daily?days=30 (aggregated)

;Incident
:An outage, disruption, or degradation reported on the status page. Incidents follow a lifecycle and can affect multiple services.
:'''Attributes:''' title, status (investigating, identified, monitoring, resolved), impact (none, minor, major, critical), start_date, update_date, end_date.
:'''Database tables:''' incident, incident_update, incident_service

;Incident Update
:A timestamped status change within an incident, forming the incident timeline.
:'''Attributes:''' incident_id, status, message.
:'''Database table:''' incident_update

;Authentication
:Admin access is controlled by JWT tokens signed with JWT_SECRET. There is no user table, no user accounts, and no permissions system. A single admin role exists. Tokens are generated via CLI and pasted into the login page.
:'''Token payload:''' { role: 'admin' }
:'''Endpoint:''' POST /api/auth/verify

;Maintenance
:A scheduled maintenance window that can affect multiple services.
:'''Attributes:''' title, description, scheduled_start, scheduled_end, status (scheduled, in_progress, completed).
:'''Database tables:''' maintenance, maintenance_service

;Subscriber
:A user subscribed to status update notifications, either by email or webhook. Email subscribers must confirm via a token link before receiving notifications.
:'''Attributes:''' email (or webhook_url), type (email, webhook), confirmed, confirm_token, unsubscribe_token.
:'''Database table:''' subscriber (with partial unique indexes on email and webhook_url)

;Group
:A label used to visually organize services on the status page. Stored as a string field on the service table (not a separate entity). Services with the same group value are displayed together under a shared heading. Services without a group appear under "Uncategorized".

ServPulse/Domain

2026-02-17T15:32:56Z

Ieli:

ServPulse/Domain

2026-02-17T15:31:11Z

Ieli:

ServPulse/Domain

2026-02-17T15:29:06Z

Ieli:

ServPulse/Domain

2026-02-17T15:27:38Z

Ieli:

== Lexicon ==

;StatusPage
:The entity representing the status page itself.
:'''Attributes:''' title, description, URL

;Service
:A monitored entity on the status page (server, application, database, API, etc.). Services can be grouped and ordered.
:'''Attributes:''' name, group, description, url, auto_status, status (operational, degraded, partial, major, maintenance), order.
:'''Database table:''' service

;Metrics
:This concept represents the performance metrics or indicators being measured for each component, such as uptime, response time, error rates, and other relevant metrics.
:'''Attributes:''' name, value, unit, timestamp.

;Incidents
:An outage, disruption, or degradation reported on the status page. Incidents follow a lifecycle and can affect multiple services.
:'''Attributes:''' title, status (investigating, identified, monitoring, resolved), impact (none, minor, major, critical), start_date, update_date, end_date.
:'''Database tables:''' incident, incident_update, incident_service

;Incident Update
:A timestamped status change within an incident, forming the incident timeline.
:'''Attributes:''' incident_id, status, message.
:'''Database tables:''' incident_update

;Users
:This concept represents the users who view or edit the status page.
:'''Attributes:''' name, role, permissions (permissions could also be defined at role level)

ServPulse/Domain

2026-02-17T15:23:58Z

Ieli:

== Lexicon ==

;StatusPage
:The entity representing the status page itself.
:'''Attributes:''' title, description, URL

;Service
:A monitored entity on the status page (server, application, database, API, etc.). Services can be grouped and ordered.
:'''Attributes:''' name, group, description, url, auto_status, status (operational, degraded, partial, major, maintenance), order.
:'''Database table:''' service

;Metrics
:This concept represents the performance metrics or indicators being measured for each component, such as uptime, response time, error rates, and other relevant metrics.
:'''Attributes:''' name, value, unit, timestamp.

;Incidents
:This concept represents any incidents, outages, or disruptions that occur and are reported on the status page.
:'''Attributes:''' title, description, status (e.g., resolved, ongoing), severity

;Users
:This concept represents the users who view or edit the status page.
:'''Attributes:''' name, role, permissions (permissions could also be defined at role level)

ServPulse/Development guide

2026-02-17T15:21:21Z

Ieli:

== Getting started ==

git clone http://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

== 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 ==

* [[Code_conventions|Nasqueron conventions]]
* Single quotes for strings
* camelCase for variables and functions
* Vue 3 Composition API (<code><script setup></code>) 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 ===

# Add table to <code>database/init.sql</code>
# Create <code>models/resourceModel.js</code> — raw pg queries
# Create <code>controllers/resourceController.js</code> — req/res handlers
# Create <code>routes/resourceRoutes.js</code> — Express router with auth where needed
# Register routes in <code>app.js</code>
# Add tests in <code>__tests__/controllers/resourceController.test.js</code>

=== Adding a frontend component ===

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

== Axios integration ==

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

Composables (<code>useServices</code>, <code>useIncidents</code>, 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 <code>docs/workflow.md</code> in the repository for the arc diff workflow.

[[Category:ServPulse|Development guide]]
[[Category:Developer guide]]

ServPulse

2026-02-17T15:17:31Z

Ieli: /* Technology stack */

'''ServPulse''' is an open-source status-page platform for publishing the status of services, components, and infrastructure. Its goal is to make it easy to communicate incidents, maintenance, and uptime metrics in a transparent way.

ServPulse is designed to be self-hostable, simple to deploy, and extensible. It provides a foundation for teams and communities to manage status pages, integrate with monitoring tools, and notify users automatically.

The project is community-driven: contributions to the code, documentation, themes, integrations, or translations are all welcome. ServPulse aims to remain open, reliable, and adaptable to different environments, while keeping the setup and use straightforward.

== Technology stack ==
* '''Back-end'''
+ Express.js (Node.js 20) with MVC architecture
+ PostgreSQL 16 database (raw pg queries, no ORM)
+ JWT authentication
+ Nodemailer for email notifications
+ Unit tests in Jest

* '''Front-end'''
+ Vue.js 3 (Composition API with <script setup>)
+ Tailwind CSS for styling
+ Chart.js for uptime charts
+ API queried through Axios
+ Unit tests in Vitest

* '''Infrastructure'''
+ Docker Compose (development and production)

== Team ==
* [https://devcentral.nasqueron.org/p/ieli/ Eli] (lead developer)
* Amine (developer)
* [[User:Dereckson|Dereckson]] (technical advisory)

Thanks for help to map stories:

* {{u|DorianWinty}}
* Fauve

== Discussion spaces ==
* Report issues: [https://devcentral.nasqueron.org/tag/servpulse/ DevCentral]
* Team discussions: [https://discord.gg/DZQK8Dd8Xd Discord]

== Activities ==
; Analysis
* [[/Note of Intent]]
* [[/Other existing solutions]]
* [[/Development guide]]
* [[/Project identity]]: why ServPulse name
* [[/Domain]]: names used in the project
* [[/User stories]]

== Useful links ==
* [https://devcentral.nasqueron.org/project/view/149/ DevCentral project board]
* [https://devcentral.nasqueron.org/source/servpulse/ Repository]

[[Category:ServPulse]]