Platform Architecture

External integration reference

This page describes the technical architecture of the Altafid platform. It is intended for integration architects and developers who need to understand service boundaries, data flows, and where API requests are handled.

Overview

The Altafid platform is a multi-service system built on a microservices architecture. Client applications and third-party integrations reach the platform through an API Gateway, which routes requests to the appropriate backend service. The two primary services are the Core API (entity management, authentication, configuration) and the Analytics service (event ingestion and time-series queries).

For integrators: you communicate only with the API Gateway. You do not need to know which internal service handles your request — the gateway routes transparently. Your base URL is always https://api.altafid.dev.altafid.net.

System diagram

flowchart TB subgraph clients ["Client Applications"] WebApp["Web Application"] ThirdParty["Third-Party Integrations"] end subgraph gateway ["API Gateway"] GW["Gateway Service\n(Routing · Auth validation · Rate limiting)"] end subgraph services ["Backend Services"] Core["Core API Service\n(Contacts · Organisations · Households\nNotes · Staff · Views · Exports)"] Analytics["Analytics Service\n(Event ingestion · Time-series queries)"] end subgraph storage ["Data Layer"] PG[("PostgreSQL\nCore database")] AnalyticsDB[("PostgreSQL\nAnalytics database")] Redis[("Redis\nCache · Sessions")] S3["S3 Object Storage\nAttachments · Branding assets"] end WebApp --> GW ThirdParty --> GW GW --> Core GW --> Analytics Core --> PG Core --> Redis Core --> S3 Core -.->|"Publishes events\n(outbox pattern)"| Analytics Analytics --> AnalyticsDB

Service responsibilities

API Gateway

The gateway is the single entry point for all external traffic. It handles:

  • TLS termination and request routing to backend services
  • JWT token validation (tokens issued by the Core API)
  • Rate limiting and traffic shaping
  • Forwarding tenant and user identity headers to downstream services

Core API Service

The Core API is the primary application service. It manages all business entities and the workflows around them:

  • Identity and access: authentication, MFA, session management, staff provisioning
  • Entity management: contacts, organisations, households, notes, portfolio linkage
  • Configuration: tenant settings, branding, domains, pipeline stages, segments, sources
  • Data operations: tabular exports (CSV / XLSX), saved view management
  • File storage: attachment upload coordination via presigned S3 URLs
  • Event publishing: writes analytics events to an outbox table for delivery to the Analytics service

Technology: Java 21 · Spring Boot · PostgreSQL · Redis

Analytics Service

The Analytics service is a dedicated data service focused on event ingestion and querying. It is separate from the Core API to avoid coupling real-time request handling to analytical query load.

  • Event ingestion: accepts structured events from the Core API and from direct API callers
  • Query execution: runs aggregate queries with time bucketing, filtering, and grouping
  • Data storage: events are stored in a dedicated PostgreSQL database with scheduled hourly rollups for efficient querying

Technology: Java · Spring Boot · PostgreSQL

Data Layer

SystemPurpose
PostgreSQL (Core)Primary transactional database — all entity records, configuration, and audit data
PostgreSQL (Analytics)Event store and rollup tables for analytical queries
RedisMFA token cache, session invalidation, distributed locking for export jobs
S3 Object StorageNote attachments, tenant branding assets (logo, favicon)

Common data flows

Creating a contact

sequenceDiagram participant Integration as Third-Party Integration participant GW as API Gateway participant Core as Core API participant DB as PostgreSQL Integration->>GW: POST /api/contacts (JWT + headers) GW->>GW: Validate JWT, extract tenant GW->>Core: Forward request + identity headers Core->>DB: INSERT contact record Core->>Core: Publish contact.created event to outbox Core-->>GW: 201 Created + contact DTO GW-->>Integration: 201 Created + contact DTO

Querying analytics

sequenceDiagram participant Integration as Third-Party Integration participant GW as API Gateway participant Analytics as Analytics Service participant DB as Analytics DB Integration->>GW: POST /api/analytics/query (JWT + headers) GW->>GW: Validate JWT GW->>Analytics: Forward request Analytics->>DB: Execute aggregation query DB-->>Analytics: Rows Analytics-->>GW: AnalyticsResult GW-->>Integration: AnalyticsResult

Authentication flow

sequenceDiagram participant Client participant GW as API Gateway participant Core as Core API participant Redis Client->>GW: POST /api/auth/login (email + password) GW->>Core: Forward Core->>Core: Validate credentials alt MFA enabled Core-->>Client: 200 OK (mfaRequired: true, challengeId) Client->>GW: POST /api/mfa/verify-login (challengeId + TOTP code) GW->>Core: Forward Core->>Redis: Validate challenge end Core-->>Client: accessToken + refreshToken + tenantUuid

See Authentication for full details on token lifetimes, the refresh flow, and MFA setup.

Event flow: Core to Analytics

The Core API publishes events to the Analytics service using a reliable outbox pattern, ensuring no events are lost even if the Analytics service is temporarily unavailable.

flowchart LR A["Business operation\n(e.g. contact created)"] --> B["Write event to\noutbox table"] B --> C["Scheduler flushes\noutbox periodically"] C --> D["POST /api/analytics/events\nto Analytics service"] D --> E["Event stored in\nAnalytics DB"] E --> F["Hourly rollup\nscheduler"] F --> G["Aggregated tables\nfor fast queries"]

Events can also be sent directly to the Analytics service via the event ingestion API if you are instrumenting your own integration.

Integration points for third parties

As a third-party integrator, you interact with the platform through these surfaces:

SurfaceBase pathDocumentation
Authentication/api/auth, /api/mfaAuthentication
Contacts/api/contacts, /api/v2/contactsContacts
Organisations/api/organisations, /api/v2/organisationsOrganisations
Households/api/households, /api/v2/householdsHouseholds
Notes/api/notesNotes
Staff management/api/tenant-staffStaff
Saved Views/api/v1/viewsSaved Views
Tenant admin/api/tenantsTenants
Exports/api/exportsExports
Analytics queries/api/analytics/queryAnalytics
Analytics event ingest/api/analytics/eventsAnalytics — Events
Configuration lookups/api/core/platformconfigs/v1/contacts/stages, /api/core/geo/v1/countries, etc.Dynamic configuration