Skip to content

Glossary

Terminology and definitions used throughout the Portugal Odyssey platform documentation. Mixes business/domain terms (Partner, Experience, Contract, etc.) with technical infrastructure (Postgres, RabbitMQ, etc.). For deeper domain context see docs/project-overview.md.

A

Activity Log — Append-only event stream that records who did what, when, on a Partner / Service / Contract entity. Powered by RabbitMQ topic exchange activity-log. Consumer side currently dormant after analytics-service was removed in W2-4 (2026-04-30); audit timeline UI to be wired against a future KPI store.

Admin — Top-level IAM role (role: admin). Platform staff who oversee partner onboarding, contract templates, dispute resolution, and global configuration. See project-overview.md §2.1.

API Gateway — Single entry point for all REST traffic from browsers and external integrations; rate-limits, authenticates, and routes to the per-service backend. Lives at services/api-gateway (Express/TS).

Auth Service — NestJS facade in front of Keycloak that exposes a REST + GraphQL surface (Apollo) for the consoles to drive OIDC flows.

Availability Rule — Expression that constrains when a PartnerService can be booked. Composed of (1) a ServiceCalendar defining base availability windows, (2) ServiceUnavailableDays (specific dates and recurring weekdays that block the calendar), and (3) capacity bounds (min_people, max_people). Stored in the partner-service parameters JSON and resolved live by calendar-service (ADR-001).

B

Booking — A confirmed reservation against a PartnerService for a specific time slot, validated against the service's Availability Rules and Capacity. Domain still in scope; the standalone booking-service was a 65-LoC stub and was removed in W2-1 (2026-04-30) — reservation lifecycle currently handled inline by experience-service until a real bookings service is rebuilt.

C

Calendar Template — Reusable ServiceCalendar definition (period + slot pattern) that can be cloned across multiple PartnerService records, e.g. a "Summer Tours Schedule" template applied to several walking tours. Lives in calendar-service.

CI/CD — Continuous Integration/Continuous Delivery. po-platform runs on GitLab CI (not GitHub Actions). Pipelines defined in .gitlab-ci.yml and .gitlab-ci/{frontend,services,infrastructure,security}.yml.

CMS — Content Management System. Strapi v5 (services/strapi-cms) hosts editorial content (landing pages, partner data, copy).

Contract — Legal agreement between the platform and a Partner. Two scopes: PARTNER_LEVEL (general partnership terms) and SERVICE_LEVEL (specific to a single PartnerService). Lifecycle: DRAFT → ACTIVE → EXPIRED|TERMINATED. Owned by contract-service. PDF generation happens via document-signing-service against templates in Postgres.

Customer — Top-level IAM role (role: customer). End-users who book Experiences. Profile data in user-management.

D

Dev — Development environment. Local Docker Compose stack started via make dev; uses self-signed TLS at *.dev.portugalodyssey.pt.

Docker Compose — Tool for orchestrating multi-container stacks. po-platform layers infrastructure/compose/{infrastructure,development,qualification,production,shared}.yml per environment.

Docling — Open-source document conversion library used by ai-service's RAG pipeline (folded in from rag-service in W2-7, 2026-04-30) to parse partner-uploaded PDFs/DOCX into markdown for vectorization.

E

Exception (Calendar Exception) — A booking-affecting deviation from a ServiceCalendar for a specific date/time-slot — typically a one-off close, rescheduling, or override of capacity. Stored atomically in calendar-service since plan 016. Sync'd both ways via ICS Sync.

Experience — Customer-facing curated travel package, AI-assembled from one or more PartnerService records based on the customer's context (temporal, spatial, social, environmental). Lifecycle: PENDING → ACTIVE → COMPLETED|CANCELLED. Owned by experience-service.

Experience Service — Microservice that hosts the catalog of PartnerService records and the AI matching layer that assembles them into Experiences for a given customer context.

F

File Service — Storage abstraction across MinIO/S3/local filesystem. All partner uploads (compliance documents, service media, signed contract PDFs) flow through it.

Frontend — One of three Vite + React 19 + TS apps: - frontends/public-fo — customer-facing site at portugalodyssey.pt. - frontends/partner-console — partner self-service at partner.portugalodyssey.pt. - frontends/admin-console — staff console at admin.portugalodyssey.pt.

G

GitLab — po-platform's git host. Repository: gitlab.com/portugalodissey/po-platform. Container registry hosts CI-built images.

I

ICS Sync — Two-way synchronization between calendar-service's availability/exception state and external calendars (iCloud, Google Calendar, etc.) via the iCalendar (.ics) format. Per-partner feed tokens scope read access. Implementation in plan 014 + 016.

IAM — Identity & Access Management. po-platform delegates to Keycloak realms. Realm definition committed to infrastructure/keycloak/realm-export.json.

K

Keycloak — Open-source OAuth2/OIDC identity provider. Hosts the portugal-odyssey realm with the three top-level roles (admin, partner, customer).

M

MCP (Model Context Protocol) — Protocol for exposing tools to AI agents. The platform's single MCP endpoint lives in ai-service at /api/v1/mcp (after W1-5 consolidation). Hosts 9 tools: 6 local ai.* and 3 rag.* proxies.

Microservices — Architecture pattern where the platform is built as 13 loosely coupled services (Node + Python + Strapi) post Wave-2 consolidation. See system-overview.md for the full registry.

MinIO — S3-compatible object store used for file storage in dev/qual; production can swap to AWS S3 or GCS via file-service's adapter layer.

N

NestJS — TypeScript framework used by ~half the Node services. Express/TS is used for thinner gateway-style services.

Notification Service — Hub for outbound notifications across three channels: email (Nodemailer/MailHog in dev), websocket (Socket.IO for in-app toasts), and push. Consumes RabbitMQ events on partner.events and notification.events exchanges.

O

OAuth2 / OIDC — Authorization and identity protocols served by Keycloak.

P

Partner — Top-level IAM role (role: partner). Service provider (hotel, tour operator, transfer company, etc.) that lists PartnerService records on the platform. Lifecycle: PENDING → ACTIVE → SUSPENDED → INACTIVE. Owned by partner-service.

PartnerService — Atomic sellable service offering provided by a Partner. Types: ACCOMMODATION, TRANSPORT, ACTIVITY, INSURANCE, FOOD_BEVERAGE, CUSTOM. The parameters JSON holds pricing/capacity/duration/multimedia/lifecycle hooks. The unit assembled into Experiences by AI matching.

Payment Service — Stripe integration. Handles payment intents, webhook validation, and refunds.

pgvector — Postgres extension providing vector similarity search. Adopted in W1-4 (replacing Qdrant). Schema: infrastructure/migrations/rag/00001_pgvector_initial.sql (managed by dbmate per ADR-003).

PostgreSQL — Primary relational store. Image is pgvector/pgvector:pg15 since W1-4. Per-service databases (booking, experience, iam, calendar, rag, etc.) created by init-multiple-databases.sh.

Prod — Production environment. Live deploys at portugalodyssey.pt, partner.portugalodyssey.pt, admin.portugalodyssey.pt. Manual deploy gate (GitLab UI).

Q

Qdrant — Vector database, retired in W1-4 (replaced by pgvector).

Qual — Qualification environment. Pre-prod soak; auto-deploys on merge to main. URLs at *.qual.portugalodyssey.pt.

R

RabbitMQ — Message broker used for service-to-service async communication. Exchanges seeded from infrastructure/config/rabbitmq/definitions.json. Topics include partner.events, activity-log, calendar-sync, notification.events.

RAG (Retrieval-Augmented Generation) — Pattern where an LLM answers a query by first retrieving relevant context from a vector store. Implemented by ai-service over the rag_document_vectors pgvector table (folded in from the standalone rag-service in W2-7, 2026-04-30).

RAG Service (retired W2-7, 2026-04-30) — Was an internal-only Python service that ingested partner documents (Docling → embeddings → pgvector). Consolidated into ai-service; the /api/v1/{search,chat,convert} endpoints, document-uploaded/deleted RabbitMQ consumer, and asyncpg pool now live in-process there.

Redis — In-memory store used for caching, sessions, rate-limiting, and short-lived state.

Review Service — Reviews & ratings for PartnerService records, with stub external integrations (Yelp/Tripadvisor/Google) currently mocked.

S

Service — In domain context: a sellable PartnerService. In infrastructure context: a microservice container (api-gateway, experience-service, etc.). Disambiguate by surrounding language.

Strapi — Headless CMS hosted at services/strapi-cms (v5). Manages editorial content; not the partner/contract/booking data which lives in dedicated services.

T

Tenant Slug (tenant_slug) — Multi-tenancy partition key on Partner and downstream entities. Lets the same Postgres+services support multiple isolated customer organizations later. Currently every Partner has a tenant_slug but only one tenant exists in production.

Traefik — v3 reverse proxy with Let's Encrypt; terminates TLS, routes by hostname to the right service container, exposes the dashboard at traefik.portugalodyssey.pt.

U

User Management — Service handling customer profile data and preferences (separate from auth-service's identity layer).

V

VHost (Virtual Host) — RabbitMQ namespace that isolates exchanges/queues. po-platform uses portugal_odyssey_dev, portugal_odyssey_qual, portugal_odyssey_prod.

VPS — Virtual Private Server. Single host runs both qual and prod stacks via separate compose project labels.

See Also