This document presents a comprehensive overview of the activities, methodologies, and key results associated with the Toolkit. Its purpose is to detail the architecture, components, and their relationships, as well as the installation, configuration, and implementation procedures for a results-based traceability and payment project using the existing toolkit, secure authentication mechanisms, blockchain traceability, and payments via tokens and stablecoins.

1. General Architecture Diagram
2. Database
3. SSO (Authentication)
4. Backend (API)
5. Frontend

This diagram describes the four main components for running the PPR application and their relationships.

https://github.com/mongodb/mongo

docker run -d \
  --name mongodb \
  -p 27017:27017 \
  -e MONGO_INITDB_ROOT_USERNAME=admin \
  -e MONGO_INITDB_ROOT_PASSWORD=admin123 \
  mongo:latest

https://github.com/keycloak/keycloak

The application requires a properly configured Keycloak server for authentication. Below is the required setup.

• Create a new realm named ppr-realm
• Configure the realm settings:
  • Enable user registration if needed
  • Set session timeouts as required

Create a client for the backend API:

Valid Redirect URIs

http://localhost:3000/*
https://your-production-domain.com/*

Create the following realm roles:

1. Go to Realm Settings → Keys
2. Click on the Public key button for the RSA key
3. Copy the key and add it to your .env:

KEYCLOAK_REALM_PUBLIC_KEY="<realm-pk>"

KEYCLOAK_AUTH_SERVER_URL="https://your-keycloak.example.com"
KEYCLOAK_REALM="ppr-realm"
KEYCLOAK_CLIENT_ID="ppr-api-client"
KEYCLOAK_SECRET="<your-client-secret>"
KEYCLOAK_REALM_PUBLIC_KEY="<your-realm-public-key>"

Note: The backend uses nest-keycloak-connect for JWT validation. All API endpoints (except /health) require a valid Bearer token.

https://github.com/LACNetNetworks/PPR/tree/main/ppr-backend

A robust NestJS backend API for the PPR platform, enabling project funding management, evidence tracking, and blockchain integration for transparency.

The project follows Clean Architecture principles with three main layers:

src/
├── application/     # Use cases and DTOs (business logic)
├── domain/          # Entities, repositories interfaces, enums
├── infrastructure/  # External concerns (HTTP, DB, auth, integrations)
└── bootstrap/       # App initialization and configuration

• Node.js 22.x (see Dockerfile)
• MongoDB instance (local or remote)
• Keycloak server configured with ppr-realm
• Access to LNet network (optional, for blockchain features)
• Access to ZKSync Network
• Access to any EVM System

npm install

Copy .env.example to .env and configure:

# Server
NODE_ENV="development"
PORT="3000"
GLOBAL_PREFIX="ppr"

# MongoDB
MONGODB_URI="mongodb://user:pass@localhost:27017/ppr_db"
MONGODB_DB="ppr_db"

# Keycloak
KEYCLOAK_AUTH_SERVER_URL="https://your-keycloak.example.com"
KEYCLOAK_REALM="ppr-realm"
KEYCLOAK_CLIENT_ID="ppr-api-client"
KEYCLOAK_REALM_PUBLIC_KEY="<your-public-key>"

# External Services
FILE_STORE_API_URL="<file-storage-api-url>"
FILE_STORE_API_KEY="<your-api-key>"

# Blockchain (optional)
RPC_URL="<lacchain-rpc-url>"
PRIVATE_KEY="<blockchain-private-key>"
ADDRESS_CONTRACT="<smart-contract-address>"

# Development (with hot reload)
npm run start:dev

# Production
npm run build
npm run start:prod

• API Base URL: http://localhost:3000/ppr
• Swagger Docs: http://localhost:3000/ppr/docs
• Health Check: http://localhost:3000/ppr/health

Note: All endpoints require Bearer token authentication via Keycloak.

# Build image
docker build -t ppr-backend .

# Run container
docker run -p 3000:3000 --env-file .env ppr-backend

docker-compose up -d

https://github.com/LACNetNetworks/PPR/tree/main/ppr-frontend

A modern Next.js 15 frontend for the PPR platform, providing role-based dashboards for project funding management, evidence tracking, and contribution monitoring.

src/
├── app/                    # Next.js App Router
│   ├── (app)/              # Protected routes
│   │   ├── sponsor/        # Sponsor dashboard
│   │   ├── provider/       # Provider dashboard
│   │   ├── user/           # User dashboard
│   │   └── verifier/       # Verifier dashboard
│   └── (auth)/             # Auth routes (login, register)
├── components/             # Reusable UI components
│   ├── grids/              # Grid layouts
│   ├── tables/             # Data tables
│   ├── dashboards/         # Dashboard components
│   ├── sidebars/           # Navigation sidebars
│   └── ...                 # Modals, forms, etc.
├── hooks/                  # Custom React hooks
├── lib/                    # Utilities and API services
└── types/                  # TypeScript types

• Node.js 18.x or later
• npm 9.x or later
• Access to the PPR Backend API
• Keycloak server for authentication

npm install

Create .env.local:

NEXT_PUBLIC_API_URL=http://localhost:3000/ppr
NEXT_PUBLIC_KEYCLOAK_URL=https://your-keycloak.example.com
NEXT_PUBLIC_KEYCLOAK_REALM=ppr-realm
NEXT_PUBLIC_KEYCLOAK_CLIENT_ID=ppr-frontend

npm run dev

The app will be available at http://localhost:5173.

npm run build
npm run start

# Build image
docker build -t ppr-frontend .

# Run container
docker run -p 8080:8080 ppr-frontend

The production container runs on port 8080.

The frontend connects to the backend using:

• src/lib/api-client.ts — Axios-based HTTP client with auth
• src/lib/api-services.ts — React hooks for API operations (client-side)
• src/lib/api-services-server.ts — Server-side API calls

import { useFetchProjects, useCreateProject } from '@/lib/api-services'

function ProjectsList() {
  const fetchProjects = useFetchProjects()
  const createProject = useCreateProject()

  useEffect(() => {
    fetchProjects().then(setProjects)
  }, [])

  const handleCreate = async (data) => {
    await createProject(data)
  }
}

A custom Keycloak login theme is included in keycloak-login-theme/. Deploy to your Keycloak server's themes/ directory.

The frontend requires a Keycloak server for authentication. It uses keycloak-js and @react-keycloak/web for client-side authentication.

Use the same ppr-realm as the backend. Ensure the following are configured:

• Realm name: ppr-realm
• Login settings: Configure as needed (registration, password policies, etc.)

Create a public client for the frontend (separate from the backend client):

Valid Redirect URIs

http://localhost:5173/*
https://your_domain.com/*

http://localhost:5173
https://yourdomain.com

Users should be assigned one role that determines their dashboard access.

NEXT_PUBLIC_KEYCLOAK_URL="https://your-keycloak.example.com"
NEXT_PUBLIC_KEYCLOAK_REALM="ppr-realm"
NEXT_PUBLIC_KEYCLOAK_CLIENT_ID="ppr-frontend"

1. User navigates to the app
2. KeycloakProvider initializes and checks for existing session
3. If not authenticated, user is redirected to Keycloak login
4. After login, Keycloak redirects back with tokens
5. Frontend stores tokens and includes them in API requests

To use the custom theme:

1. Copy keycloak-login-theme/ to <KEYCLOAK_HOME>/themes/ppr-theme
2. In Keycloak Admin Console, go to Realm Settings → Themes
3. Set Login Theme to ppr-theme