Skip to main content

VeriMe Platform Architecture

VeriMe is designed as a scalable, privacy-first identity verification platform for researchers. This document provides an overview of the system architecture and key components.

System Architecture​

The following diagram illustrates the high-level architecture of the VeriMe platform:

Architecture Layers​

User Layer​

The user layer consists of multiple client applications that researchers and subscribers interact with:

  • Web Application: Primary browser-based interface for account management and verification
  • Mobile App: iOS and Android applications for on-the-go access
  • Research Portal: Integrated interfaces for research institutions and data repositories

All client applications communicate with the backend through the API Gateway layer.

API Gateway Layer​

The API Gateway provides centralized request handling and cross-cutting concerns:

  • API Gateway: Routes requests to appropriate services, handles versioning
  • Rate Limiter: Protects services from abuse with configurable rate limits per subscriber
  • Authentication: JWT-based authentication and authorization

Service Layer​

Core business logic is organized into focused microservices:

Verification Service​

Handles identity verification logic:

  • Policy evaluation and compliance checking
  • Verification request processing
  • Assurance level determination
  • Integration with voucher system

Voucher Service​

Manages verification vouchers:

  • Voucher lifecycle (issue, send, redeem, expire)
  • State management (QUEUED, SENT, DELIVERED, REDEEMED, etc.)
  • Resend and supersede operations
  • Billing integration

Identity Service​

Manages user identity with privacy-first approach:

  • PII-minimal storage
  • Identity attribute management
  • Subject identifier generation
  • Account linking

Notification Service​

Handles all outbound communications:

  • Email delivery
  • SMS notifications
  • Webhook dispatching
  • Delivery tracking and bounce handling

Data Layer​

Each service has its own database following the database-per-service pattern:

  • User DB: PII-minimal user profile data
  • Verification DB: Verification records and policy attestations
  • Voucher DB: Voucher state and history
  • Audit Log: Immutable audit trail for compliance

All services write to the centralized Audit Log for comprehensive tracking.

External Services​

VeriMe integrates with third-party services for communication:

  • Email Provider: Transactional email delivery (SendGrid, AWS SES, etc.)
  • SMS Gateway: SMS verification code delivery (Twilio, etc.)

Key Design Principles​

Privacy-First Architecture​

VeriMe is designed to minimize PII (Personally Identifiable Information) storage and exposure:

  1. PII Minimization: Only essential identity attributes are stored
  2. Data Isolation: Sensitive data is segregated in the User DB with strict access controls
  3. Pseudonymization: Subject identifiers used in verification records instead of direct PII
  4. Audit Logging: All access to PII is logged for compliance

Scalability​

The architecture supports horizontal scaling:

  • Stateless Services: All services are stateless and can scale independently
  • Database Sharding: User and verification data can be sharded by institution or geography
  • Caching: Redis caching layer for frequently accessed data (not shown in diagram)
  • Async Processing: Voucher sending and notifications use message queues

Reliability​

Multiple layers ensure high availability:

  • Health Checks: All services expose health check endpoints
  • Circuit Breakers: Prevents cascading failures between services
  • Retry Logic: Automatic retries for transient failures
  • Graceful Degradation: System continues to function with reduced capabilities if non-critical services fail

Security​

Security is embedded at every layer:

  • Authentication: JWT tokens with short expiration times
  • Authorization: Fine-grained RBAC (Role-Based Access Control)
  • Encryption: TLS for all communications, encryption at rest for sensitive data
  • Rate Limiting: Prevents abuse and DDoS attacks
  • Input Validation: All inputs sanitized and validated

User Registration Flow​

Here's how a researcher registers and verifies their identity:

API Environments​

VeriMe provides two environments for API integration:

Production​

  • Base URL: https://verime.coop/api/v1
  • Purpose: Live production data and operations
  • Authentication: Production API keys from your VeriMe account

Sandbox​

  • Base URL: https://sandbox.verime.coop/api/v1
  • Purpose: Testing and development without affecting production data
  • Authentication: Sandbox API keys from your VeriMe dashboard
Development Best Practice

Always develop and test your integration in the sandbox environment before deploying to production. This ensures you don't accidentally trigger real verifications or send actual emails during testing.

Technology Stack​

  • API Services: Node.js with TypeScript
  • Databases: PostgreSQL (relational), Redis (cache)
  • Message Queue: RabbitMQ or AWS SQS
  • Email: SendGrid or AWS SES
  • Infrastructure: Docker, Kubernetes
  • Monitoring: Prometheus, Grafana
  • Logging: ELK Stack (Elasticsearch, Logstash, Kibana)

Next Steps​