Welcome to IVISS.
IVISS is a multi-tenant platform for law-enforcement and regulatory teams to run roadside controls, verify vehicle compliance, and manage enforcement workflows.
This README is here to make your work safer, faster, and more effective. It is the entry point for developers, operators, and reviewers. It gives a concise map of the system, local setup, architecture boundaries, security model, API/testing conventions, and where to find the full detailed documentation.
-
5.1Prerequisites 5.2 Configuration (
.env) 5.3 Startup 5.4 Useful Commands
IVISS helps agencies:
- Identify vehicles (manual entry, photo/OCR workflows).
- Perform field control operations and keep traceable control history.
- Trigger and track enforcement actions.
- Operate with role-based access control in a multi-organization environment.
- Use a mobile-first web experience with PWA capabilities.
For system overview and functional context, see docs/overview.md.
High-level architecture:
- Frontend: React + TypeScript + Vite (mobile-first SPA, PWA-enabled)
- Backend: Rust + Axum + SQLx (REST API + OpenAPI)
- Database: PostgreSQL 15
- Infrastructure: Docker Compose (local), Terraform + Ansible + GitHub Actions (deployment)
Main design choices:
- Multi-tenant data isolation by organization.
- Backend-generated OpenAPI contract consumed by frontend codegen.
- Role-based access control enforced in backend middleware.
- Infrastructure-as-Code and automated CI/CD pipelines.
For complete architecture diagrams and rationale, see:
- React, TypeScript, Vite
- Tailwind CSS + shadcn/ui (Radix primitives)
- TanStack Query, React Router
- Vitest + Testing Library
- Rust, Cargo, Axum, Tokio
- SQLx (PostgreSQL)
- Utoipa + Swagger UI (OpenAPI generation and docs)
- Docker / Docker Compose
- GitHub Actions CI/CD
- AWS Lightsail (deployment target)
Core model:
- Organization-scoped data and workflows.
- RBAC across
admin,manager(business label: supervisor),org_admin, andagentroles. - JWT-based authentication with role-aware access middleware.
- Audit-oriented flows for sensitive operations.
Security notes:
- External providers (SMS/Email) are configured via environment variables.
- Secrets must never be committed.
- Authentication/session controls are handled server-side.
For full details, see:
- Docker Engine 20.10+
- Docker Compose v2+
- Node.js 20+ (for frontend local dev and tooling)
- Rust toolchain + Cargo (for backend local build/test)
cp .env.example .envMinimum values for local backend startup:
POSTGRES_PASSWORDEXTERNAL_POSTGRES_PASSWORDJWT_PRIVATE_KEY_PEMJWT_PUBLIC_KEY_PEMACTIVATION_CODE_PEPPERSMS_PROVIDER
Recommended for end-to-end back-office flows:
EMAIL_PROVIDER(mock,resend,lettre/smtp)- Provider credentials for the selected email mode
Notes:
- The meaning of all those env varraibles are correctly documented in the
.env.examplefile - Real org-admin email delivery (temporary password) requires a real provider (
resendorlettre/smtp) and valid credentials.
For the full setup matrix, see docs/developer/getting-started.md.
docker compose --profile dev up -d --buildUseful local URLs:
- Frontend: http://localhost:8080
- Backend health: http://localhost:3000/api/v1/health
- Swagger UI: http://localhost:3000/docs
- OpenAPI JSON: http://localhost:3000/api-doc/openapi.json
- Adminer: http://localhost:8081
- Metrics health: http://localhost:9091/health
# Service status
docker compose ps
# Logs
docker compose logs -f backend
docker compose logs -f frontend
# Stop stack
docker compose down
# Stop + remove local volumes (destructive)
docker compose down -vFrontend outside Docker (optional):
cd frontend
npm install
npm run devFrontend structure is organized around routes, pages, reusable components, hooks, and generated OpenAPI client layers.
For the complete frontend architecture and developer breakdown, see:
Backend is an Axum service with modular boundaries for handlers, services, queries, middleware, DTOs, and tests.
Key entry points:
- Runtime:
iviss-backend/src/main.rs - Routes:
iviss-backend/src/routes.rs - OpenAPI:
iviss-backend/src/api_doc.rs
For complete backend structure and conventions, see:
IVISS uses PostgreSQL with SQLx migrations and seed mechanisms.
Main domains include:
- Organizations and users/roles
- Vehicle registry and statuses
- Control records and actions
- Pending submission workflow
- Audit logs
For full schema and DB workflow documentation, see:
API contract is generated from backend code and exposed through OpenAPI.
References:
- Swagger UI (local): http://localhost:3000/docs
- OpenAPI JSON (local): http://localhost:3000/api-doc/openapi.json
- Frontend snapshot:
frontend/openapi.json
API implementation and conventions are documented in:
Testing is split by subsystem:
- Backend: Rust tests, integration tests, DB tests (Testcontainers)
- Frontend: unit/component tests with Vitest + Testing Library
- CI: workflow-based validation for build, lint, type checks, tests, coverage, and security scans
For full commands and CI mapping, see:
Project standards cover:
- Code style and module ownership
- API/DB change discipline
- Security defaults
- Conventional commits and PR hygiene
See:
Use a layered troubleshooting approach:
- Service health and logs
- Env/config validation
- Auth/RBAC checks
- OpenAPI/codegen sync issues
See:
Production deployment model:
- Infrastructure provisioning: Terraform
- Server configuration and rollout: Ansible + Docker Compose
- Automation: GitHub Actions
- Target: AWS Lightsail
For full deployment procedures and operational details, see:
Operational observability includes:
- Prometheus scraping
- Grafana dashboards
- Service-level health endpoints and container logs
See:
- Use dedicated feature branches.
- Keep PRs focused and reviewable.
- Update docs whenever behavior, interfaces, or workflows change.
- Run relevant local checks before opening a PR.
Developer contribution standards:
iviss/
├── .github/
│ └── workflows/
├── docs/ # All documentation
│ ├── architecture_spec.md
│ └── developer/
│ ├── README.md
│ ├── ...
├── frontend/ # React Frontend
│ ├── src/
│ │ ├── components/
│ │ ├── hooks/
│ │ ├── pages/
│ │ ├── router/
│ │ ├── services/
│ │ └── openapi-rq/
│ ├── public/
│ ├── package.json
│ ├── vite.config.ts
│ └── openapi.json
├── iviss-backend/ # Rust Backend
│ ├── src/
│ │ ├── handlers/
│ │ ├── services/
│ │ ├── queries/
│ │ ├── middleware/
│ │ ├── dto/
│ │ ├── tests/
│ │ ├── main.rs
│ │ ├── routes.rs
│ │ └── api_doc.rs
│ ├── migrations/ # SQL migrations
│ ├── seeds/
│ ├── scripts/ # Utility scripts
│ └── Cargo.toml
├── infra/ # Infrastructure as Code
│ ├── terraform/
│ ├── ansible/
│ └── scripts/
├── monitoring/ # Observability
│ ├── prometheus/
│ └── grafana/
├── scripts/ # Utility scripts
├── docker-compose.yml
├── .env.example
└── README.md
For detailed structure, see docs/developer/project-structure.md.
- docs/overview.md
- docs/architecture_spec.md
- docs/deployment_guide.md
- docs/developer/README.md
- docs/developer/getting-started.md
- docs/developer/api.md
- docs/developer/database.md
- docs/developer/testing.md
- docs/developer/coding-standards.md
- docs/developer/debugging.md
This project is proprietary. All rights reserved.
Version: 1.0 Last Updated: May 04, 2026 Author: IVISS Development Team
For the latest version of this guide, check the Help section in the IVISS back-office or contact your system administrator.