rrstudio Dashboards

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.


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:

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:

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:

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.