Getting started with Providentia
This guide takes you from the download to your own dashboard in six steps: run it, make it look
like your product, add a page, connect your backend, apply roles and deploy. The README.md in the
download is the full reference; this page is the path through it.
- Live demo: https://demo.rr-dev.eu/providentia/overview
- API reference (every endpoint the template calls): https://demo.rr-dev.eu/docs/providentia/
1. Install and run
You need Node.js 22.22+, 24.15+ or 26+. A global Angular CLI is not needed.
npm install
npm start # http://localhost:4200
Sign in with demo@providentia.app / providentia-demo, or register a new account.
Out of the box the app runs in mock mode: every page talks to an in-browser fake backend
with realistic data, latency and errors, and saves your changes in localStorage. You can build the
whole UI before your backend exists, then switch to it with one line (step 4).
Two things worth trying in the running app:
- Settings → Appearance → Mock API: simulate a slow network or failing requests to see skeletons, error states and Retry buttons.
- Account menu → Preview as role: see the app as an Admin, Member or Viewer.
To start from a clean demo, clear the site's localStorage in the browser's dev tools.
2. Make it yours
Name and logo
Search the project for Providentia (sidebar, sign-in pages, page titles in app.routes.ts,
index.html). The logo mark is the logo icon in src/app/shared/ui/icon.ts: replace its SVG
markup with yours, then swap public/favicon.svg, favicon.ico and apple-touch-icon.png.
Brand color
All colors are tokens in src/styles.css, one block for light and one for dark. To use your brand
color, change the --app-accent* tokens in both blocks:
:root {
--app-accent: #0f766e; /* buttons, links, active menu item */
--app-accent-hover: #115e59;
--app-accent-soft: #ccfbf1; /* tinted backgrounds */
--app-accent-ink: #ffffff; /* text on accent buttons */
}
.dark {
--app-accent: #2dd4bf;
/* … the same four tokens, tuned for the dark background */
}
Every button, badge, chart highlight and focus ring follows. Check that text on the accent and accent text on surfaces still reach WCAG AA contrast (4.5:1).
Links
src/app/config/links.ts holds the optional "Getting started", "API reference" and "Support" links
of the sidebar and the "Download" button of the topbar. They ship empty, so they are hidden: fill them in or leave them.
3. Add a page
As an example, a Projects page with its own data. Every feature follows the same layout, so once you have done this you can read the rest of the code.
3.1 Model and contract
src/app/features/projects/data-access/projects.models.ts
export interface Project {
id: string;
name: string;
owner: string;
status: 'active' | 'paused';
}
src/app/features/projects/data-access/projects.api.ts: the page depends only on this class.
import { Observable } from 'rxjs';
import { Project } from './projects.models';
export abstract class ProjectsApi {
abstract list(): Observable<Project[]>;
}
3.2 Mock and HTTP implementations
projects.api.mock.ts: data in the browser, with the same simulated latency and errors as the
rest of the app.
import { Injectable } from '@angular/core';
import { Observable } from 'rxjs';
import { mockResponse } from '../../../core/mock/mock-response';
import { ProjectsApi } from './projects.api';
import { Project } from './projects.models';
const PROJECTS: Project[] = [
{ id: 'p1', name: 'Website redesign', owner: 'Priya Raman', status: 'active' },
{ id: 'p2', name: 'Mobile app', owner: 'Daniel Okafor', status: 'paused' },
];
@Injectable()
export class MockProjectsApi extends ProjectsApi {
list(): Observable<Project[]> {
return mockResponse(() => PROJECTS);
}
}
projects.api.http.ts: the only file that knows your backend's URL.
import { HttpClient } from '@angular/common/http';
import { Injectable, inject } from '@angular/core';
import { Observable } from 'rxjs';
import { API_BASE_URL } from '../../../core/api/api.config';
import { ProjectsApi } from './projects.api';
import { Project } from './projects.models';
@Injectable()
export class HttpProjectsApi extends ProjectsApi {
private readonly http = inject(HttpClient);
private readonly baseUrl = inject(API_BASE_URL);
list(): Observable<Project[]> {
return this.http.get<Project[]>(`${this.baseUrl}/projects`);
}
}
3.3 The page
src/app/features/projects/projects.page.ts
import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { rxResource } from '@angular/core/rxjs-interop';
import { PageHeader } from '../../shared/ui/page-header';
import { ProjectsApi } from './data-access/projects.api';
@Component({
selector: 'app-projects-page',
changeDetection: ChangeDetectionStrategy.OnPush,
imports: [PageHeader],
template: `
<app-page-header title="Projects" description="Everything your team is working on." />
<div class="card">
@if (projects.isLoading()) {
<p class="p-4 text-sm text-muted">Loading…</p>
} @else if (projects.error()) {
<p class="p-4 text-sm text-bad">Projects could not be loaded.</p>
} @else {
<ul class="divide-y divide-line">
@for (project of projects.value(); track project.id) {
<li class="flex items-center justify-between p-4">
<div>
<p class="font-medium">{{ project.name }}</p>
<p class="text-sm text-muted">{{ project.owner }}</p>
</div>
<span class="badge">{{ project.status }}</span>
</li>
}
</ul>
}
</div>
`,
})
export class ProjectsPage {
private readonly api = inject(ProjectsApi);
protected readonly projects = rxResource({ stream: () => this.api.list() });
}
For loading skeletons, empty states and tables, copy from an existing page such as
features/reports/reports.page.ts and reuse the pieces in shared/ui (<app-load-error>,
<app-pagination>, <app-kpi-card>, <app-chart>…).
3.4 Route and menu
src/app/features/projects/projects.routes.ts binds the contract to the mock or HTTP class,
depending on the mode chosen in app.config.ts:
import { Routes } from '@angular/router';
import { apiProvider } from '../../core/api/provide-api';
import { ProjectsApi } from './data-access/projects.api';
import { HttpProjectsApi } from './data-access/projects.api.http';
import { MockProjectsApi } from './data-access/projects.api.mock';
import { ProjectsPage } from './projects.page';
export default [
{
path: '',
providers: [apiProvider(ProjectsApi, { mock: MockProjectsApi, http: HttpProjectsApi })],
component: ProjectsPage,
},
] satisfies Routes;
In src/app/app.routes.ts, next to the other pages inside the shell:
{
path: 'projects',
title: 'Projects · Providentia',
loadChildren: () => import('./features/projects/projects.routes'),
},
In src/app/layout/navigation.ts, add the menu entry:
{ label: 'Projects', path: '/projects', icon: 'grid' },
Icons come from shared/ui/icon.ts; to add one, paste its Lucide SVG markup
into the ICONS map. Run npm start and Projects is in the sidebar, the command palette and on
phones.
4. Connect your backend
Switch the mode
In src/app/app.config.ts:
provideApi({ mode: 'http', baseUrl: 'https://api.your-saas.com' }),
Every feature now uses its *.api.http.ts class. Nothing in the pages changes.
What your backend must answer
docs/openapi.yaml (OpenAPI 3.1) lists every endpoint, request and response the HTTP classes use.
Read it rendered at https://demo.rr-dev.eu/docs/providentia/, generate a server stub or client
types from it, or run a mock server: npx @stoplight/prism-cli mock docs/openapi.yaml.
Start with authentication. POST /auth/login receives { email, password, remember } and
returns:
{
"token": "eyJhbGciOi…",
"expiresAt": "2026-12-31T23:59:59Z",
"user": { "id": "usr_1", "name": "Alex Morgan", "email": "alex@your-saas.com", "role": "owner" }
}
From then on the interceptor (core/auth/auth.interceptor.ts) sends Authorization: Bearer <token>
with every request to baseUrl. If your API runs on another domain, allow the app's origin in its
CORS settings.
Different response shapes
If your API returns other field names, adapt in the HTTP class only, with RxJS map:
list(): Observable<Project[]> {
return this.http
.get<{ data: { uuid: string; title: string; owner_name: string; is_paused: boolean }[] }>(`${this.baseUrl}/v2/projects`)
.pipe(
map((res) =>
res.data.map((p) => ({ id: p.uuid, name: p.title, owner: p.owner_name, status: p.is_paused ? 'paused' : 'active' })),
),
);
}
One feature at a time
You can connect features one by one: keep the mock for a page whose endpoints are not ready by binding it explicitly in its routes file.
providers: [{ provide: BillingApi, useClass: MockBillingApi }],
5. Roles and permissions
The role (owner, admin, member, viewer) comes from user.role in the login response. What
each role may do is one table in src/app/core/auth/permissions.ts; the README lists it.
To protect the Projects page, add a permission to the Permission type and to the roles that
have it:
export type Permission =
| 'users.write'
// …
| 'projects.manage';
export const ROLE_PERMISSIONS: Record<UserRole, readonly Permission[]> = {
owner: [/* … */ 'projects.manage'],
admin: [/* … */ 'projects.manage'],
member: [/* … */],
viewer: [],
};
Then use it where it matters:
Menu:
{ label: 'Projects', path: '/projects', icon: 'grid', permission: 'projects.manage' }hides the entry for the other roles.Route: in
app.routes.tsthe guard shows the "no access" page to whoever opens the URL anyway;runGuardsAndResolvers: 'always'checks it again when the role changes on that page (Preview as role), as the Billing route does:{ path: 'projects', title: 'Projects · Providentia', canActivate: [permissionGuard('projects.manage')], runGuardsAndResolvers: 'always', loadChildren: () => import('./features/projects/projects.routes'), },Buttons: inject
AccessServiceand write@if (access.can('projects.manage')) { … }.
The UI only hides what a role may not do. Your backend must check the same permissions and
answer 403, otherwise anyone can call the API directly. The mock APIs already do, so you can
see how each page reacts to a 403 with Preview as role.
6. Build and deploy
npm test # unit tests
npm run e2e # end-to-end tests (run `npx playwright install` once first)
npm run build # output: dist/providentia/browser/
The output is a static site: host it on Netlify, Vercel, Cloudflare Pages, S3 or Nginx. Configure
the host to serve index.html for unknown paths (examples for each host are in the README), and
enable gzip or Brotli compression and long caching for the hashed .js and .css files.
Before going live:
provideApi({ mode: 'http', … })inapp.config.ts.- Remove the demo credentials hint from
features/auth/login/login.page.tsand the demo password hint fromfeatures/settings/security/security-settings.ts. - Replace the logo, favicons and the
Providentianame (step 2). - Check that your backend enforces the permissions (step 5).
Questions or a bug? Open an issue on GitHub.
Get Providentia
Free for personal and commercial projects, pay what you want. The demo runs entirely in your browser on generated data.