SIMAP Digital environment variables and system configuration

Environment Variables

SIMAP Digital uses Vite’s environment variable system. All client-side variables must be prefixed with VITE_ to be exposed to the browser bundle. Create a .env file at the project root before starting the dev server or running a production build.

Never commit your .env file to version control. It is listed in .gitignore by default. Use .env.example (committed) as the canonical reference template and fill in real values in your local .env only.

Variable reference

VITE_APP_NAME

string

default:"SIMAP Digital Plataforma"

Human-readable application name shown in the browser tab and PWA manifest. Optional — the app falls back to a hard-coded string if unset.

VITE_APP_VERSION

string

default:"1.0.0"

Semantic version string injected at build time. Displayed in the About screen and included in Excel export headers.

VITE_SUPABASE_URL

string

required

The base URL of your Supabase project, e.g. https://abcdefgh.supabase.co. Found in Project Settings → API → Project URL in the Supabase dashboard. Required for cloud sync; the app runs offline without it but cannot push pending records to the cloud layer.

VITE_SUPABASE_ANON_KEY

string

required

The anon (public) API key for your Supabase project. Found in Project Settings → API → Project API keys. This key is intentionally public and is safe to embed in a client bundle; Row Level Security policies (defined in 00001_init.sql) enforce data access rules server-side regardless of what the client sends.

VITE_AI_PROVIDER

string

default:"local"

Selects the AI inference backend used by the risk-scoring engine (aiService.js). Accepted values:

Value	Behaviour
`local`	Uses the browser’s built-in `window.ai` API (Chrome 127+). No external calls.
`openai`	Forwards prompts to the OpenAI API. Requires `VITE_OPENAI_API_KEY`.
`claude`	Forwards prompts to the Anthropic Claude API. Requires the corresponding key.

In a rural deployment with no internet, keep this set to local.

VITE_OPENAI_API_KEY

string

OpenAI secret key (sk-…). Only required when VITE_AI_PROVIDER=openai. Even though this variable is bundled into the client (Vite limitation), treat it as sensitive and restrict it with OpenAI’s usage policies and project-level key scoping.

Example `.env` file

Copy .env.example from the repository root and fill in your values:

# .env  — DO NOT COMMIT THIS FILE
# Copy from .env.example and fill in real values.

# ── App identity ──────────────────────────────────────────────────────────────
VITE_APP_NAME="SIMAP Digital Plataforma"
VITE_APP_VERSION="1.0.0"

# ── AI provider ───────────────────────────────────────────────────────────────
# Options: "local" | "openai" | "claude"
VITE_AI_PROVIDER="local"
VITE_OPENAI_API_KEY="sk-..."

# ── Supabase (cloud sync) ─────────────────────────────────────────────────────
VITE_SUPABASE_URL="https://tu-proyecto.supabase.co"
VITE_SUPABASE_ANON_KEY="tu-anon-key"

Runtime System Config (`DEFAULT_CONFIG`)

Beyond environment variables (which are baked in at build time), SIMAP Digital stores a mutable system configuration object in IndexedDB under the config table with the key 'general'. This allows administrators to change operational parameters at runtime — through the Admin panel — without rebuilding or redeploying the app. The defaults are declared in src/utils/constants.js:

// src/utils/constants.js
export const DEFAULT_CONFIG = {
  cuotaMensual: 3.00,
  permitirParciales: true,
  mesesGraciaCorte: 3,
};

Config field reference

cuotaMensual

number

default:"3.00"

Monthly water quota charged to each registered household, in Panamanian balboas (B/.).
All payment calculations — change computation, debt totals, the points engine, and commission splits — derive from this single value.
Changing it takes effect immediately for any new payment recorded after the save; historical records retain the amount that was in force when they were created.

permitirParciales

boolean

default:"true"

When true, the cobrador (collector) may accept partial payments and record them with tipo: 'parcial'. The saldo ledger stores the household’s running balance and estado is set to 'parcial' until the outstanding amount is cleared.
When false, only full-quota payments are accepted; the UI hides the partial payment option.

mesesGraciaCorte

number

default:"3"

The number of consecutive unpaid months after which a household’s estado is automatically promoted from 'moroso' to 'corte' (service cut-off).
The payment engine evaluates this threshold each time a saldo record is written. Lower values increase cut-off sensitivity; higher values extend the grace period.

Reading and writing config

Two async helpers in src/services/db.js wrap all config I/O:

import { getConfig, saveConfig } from './services/db';

// Read current config (falls back to DEFAULT_CONFIG if 'general' row is absent)
const cfg = await getConfig();
console.log(cfg.cuotaMensual); // e.g. 3.00

// Update a single field and persist
const updated = { ...cfg, cuotaMensual: 4.00 };
await saveConfig(updated);
// IndexedDB now holds: { key: 'general', cuotaMensual: 4.00, permitirParciales: true, mesesGraciaCorte: 3 }

getConfig() always returns a complete object: if the 'general' row has never been written (fresh install before initDB() runs), it returns DEFAULT_CONFIG directly. saveConfig(cfg) performs an IndexedDB put, so it is safe to call even when the row does not yet exist.

Build Configuration

Vite (`vite.config.js`)

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],   // JSX transform + Fast Refresh
  base: '/',            // Root-relative asset paths (required for SPA routing)
  build: {
    outDir: 'dist',     // Production bundle output directory
    sourcemap: false,   // Source maps disabled in production
  },
  server: {
    port: 5173,         // Local dev server port
    open: true,         // Auto-open browser on `npm run dev`
  },
})

Option	Value	Purpose
`plugins`	`react()`	Enables JSX compilation and React Fast Refresh in development
`base`	`'/'`	Ensures all asset imports use root-relative URLs; required when Vercel serves the SPA from `/`
`build.outDir`	`'dist'`	All compiled files land in `dist/`; this matches the Vercel `outputDirectory`
`build.sourcemap`	`false`	Source maps are omitted from the production bundle to reduce deployed asset size
`server.port`	`5173`	Default Vite dev port
`server.open`	`true`	Opens `http://localhost:5173` automatically when you run `npm run dev`

Vercel (`vercel.json`)

{
  "framework": "vite",
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "rewrites": [
    {
      "source": "/(.*)",
      "destination": "/index.html"
    }
  ]
}

The rewrites rule is essential for client-side routing. Without it, Vercel’s CDN would return a 404 for any URL other than / because dist/ contains only index.html — React Router handles path resolution in the browser, not on the server.

npm Scripts

All scripts are defined in package.json and invoked via npm run <script>.

Script	Command	Purpose
`dev`	`vite`	Starts the Vite development server on `http://localhost:5173` with Hot Module Replacement (HMR). Changes to React components and CSS are reflected instantly without a full reload.
`build`	`vite build`	Compiles and bundles the app for production into `dist/`. Runs tree-shaking, minification, and asset hashing. Output is ready to deploy to Vercel or any static host.
`preview`	`vite preview`	Serves the production bundle from `dist/` locally (default port 4173). Use this to validate the production build before deploying — behaviour may differ from `dev` because HMR and dev-only code paths are absent.
`lint`	`eslint .`	Runs ESLint across the entire source tree using the project’s flat config (`eslint.config.js`). Catches unused variables, React hook rule violations, and other static issues. Run this in CI before merging pull requests.

# Start development
npm run dev

# Production build
npm run build

# Preview the production build locally
npm run preview

# Lint the codebase
npm run lint

Service API

Configuration

SIMAP Digital environment variables and system configuration

Environment Variables

Variable reference

Example `.env` file

Runtime System Config (`DEFAULT_CONFIG`)

Config field reference

Reading and writing config

Build Configuration

Vite (`vite.config.js`)

Vercel (`vercel.json`)

npm Scripts

Build docs developers (and LLMs) love

Service API

Configuration

Documentation Index

​Environment Variables

​Variable reference

​Example .env file

​Runtime System Config (DEFAULT_CONFIG)

​Config field reference

​Reading and writing config

​Build Configuration

​Vite (vite.config.js)

​Vercel (vercel.json)

​npm Scripts

Build docs developers (and LLMs) love

Environment Variables

Variable reference

Example `.env` file

Runtime System Config (`DEFAULT_CONFIG`)

Config field reference

Reading and writing config

Build Configuration

Vite (`vite.config.js`)

Vercel (`vercel.json`)

npm Scripts