# Geo Profile Service

## Context and Purpose

Geo Profile Service is an internal trusted microservice responsible for collecting and processing country-level connection signals for authenticated users.

The service exists to solve four related problems:

- Record the observed country of authenticated requests based on local Geo-IP lookup.
- Maintain per-`device_session_id` country statistics and derive a `usual_connection_country`.
- Support administrative review workflows around user country changes.
- Detect suspicious multi-country session behavior and request blocking of suspicious sessions through `Auth / Session Service`.

The service is intentionally narrow in scope. It does not own authentication, user identity validation, or user-facing profile reads for the latest country value.

## Explicit Non-Goals

The following are intentionally out of scope for this service:

- Region-level or city-level geolocation.
- VPN, proxy, anonymizer, or hosting-provider detection.
- Automatic change of `declared_country` based on observed metrics.
- Immediate blocking of the same request that triggered suspicion.
- Global source-of-truth ownership for the current user country.
- Direct exposure of storage to other services.
- Strong audit reproducibility of historical Geo-IP lookup results by storing Geo-IP database versions.

## Place in the Existing Microservice System

The service is embedded into an already existing trusted microservice environment and integrates with:

- `Edge Service`
- `Auth / Session Service`
- `User Service`
- `Mail Service`
- Internal event bus

`Edge Service` is the producer of authenticated connection observations.

`User Service` remains the centralized owner of the latest effective `declared_country` value for normal user profile reads.

`Auth / Session Service` remains the owner of session lifecycle and session blocking.

`Mail Service` is used only for optional administrative notifications.

The event bus is used only as an auxiliary notification channel and not as the authoritative source of business state.

## Responsibility Boundaries

Geo Profile Service owns:

- Geo-IP lookup at country level using a local database.
- Storage of `observed_country` as a fact of observation.
- Per-`device_session_id` country aggregation.
- Computation of `usual_connection_country`.
- Computation and storage of `country_review_recommended`.
- Version history of `declared_country`.
- Internal administrative read APIs for geo-related user state.
- Internal command API to apply approved `declared_country` changes.
- Detection of suspicious cross-country session patterns.
- Session block requests toward `Auth / Session Service`.

Geo Profile Service does not own:

- Validation of `user_id` and `device_session_id` against external services.
- Public user profile reads for the latest country value.
- Authentication or authorization of end users.
- Final enforcement of session blocking.
- Delivery guarantees of auxiliary event notifications.
- Formal administrative SLA or rigid approval policies.

## Semantic Model

The service works with four core country-related concepts.

### declared_country

`declared_country` is the user-declared country.

Properties:

- It is a user-facing business attribute.
- The latest effective value is stored in `User Service`.
- The full version history is stored in Geo Profile Service.
- It is never changed automatically by metrics.
- It changes only through a controlled command path and administrative approval.

### observed_country

`observed_country` is the country derived from Geo-IP for a specific authenticated request.

Properties:

- It is an observation fact, not a truth claim about residence.
- It is tied to `user_id`, `device_session_id`, and observation time.
- It is derived on the server side from the source IP seen at the trusted edge.
- It is used as input into country aggregation and anomaly detection.

### usual_connection_country

`usual_connection_country` is the computed most typical country of network egress for a given `device_session_id`.

Properties:

- It is not interpreted as country of residence.
- It is calculated per `device_session_id`, not globally per account.
- It is derived from recent weighted observations with decay over time.
- It is expected to drift naturally as usage patterns change.

### country_review_recommended

`country_review_recommended` is an internal service flag that indicates that the accumulated observations justify administrative review.

Properties:

- It does not trigger automatic country change.
- It is stored durably in the service state.
- It is readable through the service API.
- Transition to `true` may also emit an event and optionally send email.

## Data Ownership Rules

The split ownership model is intentional.

- `User Service` owns the latest effective `declared_country`.
- Geo Profile Service owns the history of `declared_country` changes.
- Geo Profile Service owns `observed_country`, `usual_connection_country`, and `country_review_recommended`.

This means Geo Profile Service is the owner of the country-change process, but `User Service` is the owner of the currently effective denormalized value used by the rest of the system.

To avoid divergence:

- No service other than Geo Profile Service should directly mutate the current `declared_country` in `User Service`.
- Geo Profile Service must write the new version in its own storage first.
- Geo Profile Service must then synchronously update the current value in `User Service`.
- A version should become effective only after the `User Service` update succeeds.

## High-Level Architecture

```mermaid
flowchart LR
    Client[Client] --> Edge[Edge Service]
    Edge --> Auth[Auth / Session Service]
    Auth --> Edge

    Edge -. async flatbuffers ingest .-> Geo[Geo Profile Service]

    Geo --> User[User Service]
    Geo --> Mail[Mail Service]
    Geo --> Bus[Event Bus]
    Geo --> Auth

    AdminUI[Admin Interface] --> Edge
    Edge --> Geo
    Edge --> User
````

## Ingress Processing Model

The hot path from `Edge Service` to Geo Profile Service is intentionally asynchronous and non-blocking for the edge.

Design rules:

- `Edge Service` publishes a minimal FlatBuffers message after user authentication.
- The message contains only:

  - `user_id`
  - `device_session_id`
  - `ip_address`
- No protobuf wrapper is used.
- No business response is required from Geo Profile Service.
- The edge does not depend on this service for normal request continuation.
- Failures are treated as observability signals, not as reasons to change gateway behavior.

This design explicitly prioritizes low infrastructure complexity and low overhead on the hottest path over strict RPC semantics.

## Ingress Transport Contract

The ingress path is not modeled as conventional request-response RPC.

Recommended transport shape:

- Internal binary HTTP endpoint or similarly simple internal binary transport.
- `application/octet-stream` body encoded as FlatBuffers.
- Minimal acknowledgement such as `202 Accepted` with empty body.
- The acknowledgement is not part of business logic.
- The edge client should publish asynchronously and ignore service availability for request progression.

The service must only validate:

- FlatBuffers message integrity.
- Presence of required scalar fields.
- Basic field shape constraints.

The service must not validate:

- Whether `user_id` exists.
- Whether `device_session_id` belongs to the user.
- Whether the session is still valid.

Those concerns belong to the already trusted authentication/session layer.

## Internal Queue and Worker Pipeline

Geo Profile Service must process ingress data in its own queue and worker flow.

```mermaid
flowchart LR
    E[Edge Service] -. async flatbuffers publish .-> I[Ingest Receiver]
    I --> Q[Internal Ingest Queue]
    Q --> W[Processing Worker]
    W --> G[Geo-IP Resolver]
    G --> A[Observation Aggregator]
    A --> U[usual_connection_country Calculator]
    A --> R[country_review_recommended Evaluator]
    A --> S[Session Suspicion Detector]
    S --> B[Block Session Command]
```

The internal queue exists to decouple network acceptance from CPU and storage work.

Required properties:

- The network-facing ingest step is append/update-only.
- The worker can process observations independently from the ingest receiver.
- Expensive logic must not run inline on the network acceptance step.
- Queue backlog and processing latency must be observable.

A simple durable internal queue is preferred over a complex broker dependency for this part of the system.

## Service Interface Model

The service interface is intentionally divided into commands, queries, and events.

This split exists to preserve the architectural rules already fixed above:

- Hot-path ingest is asynchronous and write-oriented.
- Administrative reads use trusted internal JSON REST APIs.
- State-changing administrative operations follow one controlled command path.
- Events are auxiliary notifications and never the only representation of business state.

## Commands

Commands change service state or trigger downstream effects.

### Ingest Connection Observation

Purpose:

- Accept an authenticated country observation from `Edge Service`.

Caller:

- `Edge Service`

Transport:

- Internal binary transport
- FlatBuffers payload
- Async publication
- No business response

Payload:

- `user_id`
- `device_session_id`
- `ip_address`

Effects:

- Enqueue observation for processing
- Eventually resolve `observed_country`
- Update per-session country statistics
- Potentially update `usual_connection_country`
- Potentially set `country_review_recommended`
- Potentially request session blocking through `Auth / Session Service`

Important behavior:

- This command must not block edge request processing.
- Failure to send or process is an observability concern, not a gateway correctness concern.

### Apply Approved Declared Country Change

Purpose:

- Record a new approved version of `declared_country` and synchronize the current value into `User Service`.

Caller:

- Trusted internal administrative workflow
- Administrative interface backend
- Internal orchestration component

Transport:

- Trusted internal JSON REST API

Input shape:

- `user_id`
- `new_declared_country`
- actor identity or actor type
- optional reason or comment
- optional correlation metadata

Effects:

- Create immutable declared-country version record in Geo Profile Service
- Synchronize latest effective value to `User Service`
- Mark version as effective only after sync succeeds

Important behavior:

- Geo Profile Service is the owner of this mutation workflow.
- No bypass write path to `User Service` should exist for this field.

### Request Suspicious Session Block

Purpose:

- Ask `Auth / Session Service` to block suspicious `device_session_id` values.

Caller:

- Internal processing worker inside Geo Profile Service

Transport:

- Trusted internal API call from Geo Profile Service to `Auth / Session Service`

Input shape:

- `user_id`
- one or more suspicious `device_session_id`
- reason or code for block trigger
- optional evidence reference

Effects:

- Session block request is sent to `Auth / Session Service`
- Local action log is written in Geo Profile Service

Important behavior:

- Current triggering request is not interrupted.
- The effect is expected on subsequent requests.

## Queries

Queries return internal state and never mutate business state.

### List Review Candidates

Purpose:

- Return `user_id` values matching review-related filters.

Caller:

- Administrative interface
- Internal operational tooling

Transport:

- Trusted internal JSON REST API

Initial supported filter:

- `country_review_recommended=true`

Expected response characteristics:

- Pagination
- Stable ordering
- Ability to extend filter set later without changing the conceptual API class

### Read User Geo Profile

Purpose:

- Return the geo-related internal state of a single user for manual review or investigation.

Caller:

- Administrative interface
- Internal operational tooling

Transport:

- Trusted internal JSON REST API

Response should include, at minimum:

- `user_id`
- current `country_review_recommended`
- per-`device_session_id` country ranking
- per-`device_session_id` `usual_connection_country`
- observation summaries grouped by `device_session_id`
- declared-country version history
- suspicious-session indicators if present
- session-block action history if useful for operations

### Read Service Health and Operational State

Purpose:

- Expose service-operability information for internal monitoring.

Caller:

- Monitoring systems
- Internal operators

Transport:

- Internal HTTP endpoints

Response may include:

- readiness state
- liveness state
- queue lag indicators
- Geo-IP database status
- downstream integration health summaries

This query group is operational, not business-facing.

## Events

Events are emitted as auxiliary notifications. They are not sources of truth.

### Country Review Recommended

Meaning:

- `country_review_recommended` transitioned from `false` to `true` for a user.

Producer:

- Geo Profile Service

Consumers:

- Administrative workflow automation
- Internal notification consumers
- Optional future downstream internal systems

Delivery channel:

- Internal event bus

Guarantees:

- Best effort only, unless the underlying bus is later upgraded
- Loss of event must not lose the actual business state

Durable state counterpart:

- The current review flag must remain available through Geo Profile Service query APIs

### Optional Admin Email Notification

Meaning:

- Administrative email generated because a user entered review-recommended state

Producer:

- Geo Profile Service via `Mail Service`

Consumers:

- Administrators

This is operationally useful but never required for correctness.

## Data Entities

This section defines the core logical entities of the service. These are domain entities, not mandatory final physical table names.

### Country Observation

Represents a stored observation fact derived from one authenticated request.

Required logical fields:

- `user_id`
- `device_session_id`
- `observed_country`
- observation timestamp

Optional implementation fields:

- obfuscated or hashed IP representation
- internal ingestion metadata
- processing metadata

Role in the system:

- Source data for rankings
- Source data for suspicious-session detection
- Source data for review recommendations

### Device Session Country Score

Represents the weighted ranking of countries for one `device_session_id`.

Required logical fields:

- `device_session_id`
- `country_code`
- current score
- last contribution timestamp
- optional rank or ordering marker

Role in the system:

- Maintains the rolling per-session country distribution
- Supports direct derivation of `usual_connection_country`

### Device Session Geo State

Represents the current derived geographic state of one `device_session_id`.

Required logical fields:

- `device_session_id`
- current `usual_connection_country`
- last observation timestamp
- summary metadata needed by admin APIs

Role in the system:

- Read-optimized representation of session-level geo state
- Allows admin APIs to avoid recomputing from raw observations on each read

### User Review State

Represents the current review-related state for one user.

Required logical fields:

- `user_id`
- `country_review_recommended`
- last evaluation timestamp
- optional reason code or explanation marker

Role in the system:

- Durable source for review filtering
- Source of truth for admin API candidate listing
- State backing for auxiliary event emission

### Declared Country Version

Represents one immutable version of the declared country.

Required logical fields:

- `user_id`
- version identifier
- `declared_country`
- version creation timestamp
- actor identity or actor type
- optional reason or comment
- version status

Suggested version statuses:

- `recorded`
- `applied`
- `sync_failed`

Role in the system:

- Immutable history of approved country changes
- Separation between local history and currently effective external value

### Session Block Action

Represents a record of a suspicious-session block request.

Required logical fields:

- `user_id`
- `device_session_id`
- action timestamp
- reason code
- result status

Role in the system:

- Operational trace of protection actions
- Support for troubleshooting and admin inspection

## Geo-IP Source

The service uses a locally stored free Geo-IP country database.
The Geo-IP acessible via [geoip](../pkg/geoip/) package.

Requirements:

- No per-request calls to external Geo-IP services.
- The database must be actively maintained and not abandoned.
- The service only needs country-level lookup.
- Database refresh is handled internally on a schedule.

Version of the Geo-IP database is not stored with each observation, by explicit design choice.

## Observation Storage Strategy

The service does not keep a full raw IP log for every API request.

The primary stored signal is the derived country observation and its aggregates.

Recommended storage model:

- Store observation facts at country level.
- Aggregate per `device_session_id`.
- Keep enough history to compute ranking and review decisions.
- Retain no raw IP by default.
- Allow optional obfuscated or hashed IP retention only if later justified by operational needs.

A one-year observation horizon is acceptable as a starting point, subject to real data volume.

## Derived Statistics Model

The service computes a weighted ranking of countries per `device_session_id`.

Baseline principles:

- More recent observations carry more weight.
- Older observations decay over time.
- The calculation is based on recent activities, not active calendar days.
- The scoring model must remain computationally cheap and tunable.

The service must maintain, at minimum:

- Ranked observed countries for each `device_session_id`
- Current `usual_connection_country` for each `device_session_id`
- Sufficient ranking data for administrative inspection

The precise scoring formula is configurable and intentionally left outside this document.

## Suspicious Session Logic

The service must detect suspicious multi-country behavior across multiple sessions of the same user.

The intended interpretation is:

- Slow geographic drift over larger time spans is normal.
- Simultaneous or near-simultaneous active usage from conflicting countries is suspicious.
- Suspicion targets sessions, not the entire account.

Important trade-off:

- The request that caused the suspicion is allowed to proceed.
- Session blocking is requested asynchronously afterward.
- The next request from the blocked session should be rejected by `Auth / Session Service`.

```mermaid
flowchart TD
    O[New processed observation] --> D{Conflicting country pattern
    across user sessions?}
    D -- No --> N[No block action]
    D -- Yes --> C[Select suspicious device sessions]
    C --> A[Call Auth / Session Service block API]
    A --> X[Subsequent requests get rejected]
```

Exact threshold tuning is configuration-driven and may evolve without changing the service boundary.

## Country Review Recommendation Logic

The recommendation workflow is durable and queryable.

Key rules:

- `country_review_recommended` is stored as service state.
- Transition to `true` must not be represented only by an event.
- Administrative systems must be able to retrieve candidates via service API.
- Auxiliary notifications exist only to reduce polling latency.

```mermaid
flowchart LR
    P[Processed observations] --> F{Review criteria met?}
    F -- No --> K[Keep existing state]
    F -- Yes --> T[Set country_review_recommended=true]
    T --> API[Expose via internal REST API]
    T --> BUS[Publish event bus notification]
    T --> MAIL[Optionally send admin email]
```

If event delivery fails, the recommendation state still exists and remains observable through the API.

## Administrative Read API

The service exposes a trusted internal JSON REST API for administrative and operational reads.

### Review Candidate Query Endpoint

Purpose:

- Return `user_id` values for users requiring review.

Initial required filter set:

- `country_review_recommended=true`

Expected characteristics:

- Pagination support
- Stable ordering
- Simple extension path for additional filters later

### Geo Profile Query Endpoint

Purpose:

- Return the internal geo profile of a specific user for administrative inspection.

The response should include, at minimum:

- `user_id`
- current review flag
- per-`device_session_id` country ranking
- per-`device_session_id` `usual_connection_country`
- observation summaries
- declared country version history
- suspicious session markers if present
- enough information for manual administrative decision-making

The profile is grouped by `device_session_id`, because that is the primary aggregation boundary.

## Declared Country Change Command API

Geo Profile Service exposes an internal trusted command API to apply approved `declared_country` changes.

The command path must behave as follows:

- Record a new declared country version in Geo Profile Service storage.
- Synchronously update the current `declared_country` value in `User Service`.
- Mark the new version effective only if the `User Service` update succeeds.

Recommended version lifecycle:

- `recorded`
- `applied`
- `sync_failed`

This lifecycle prevents invisible divergence between history and current value.

```mermaid
sequenceDiagram
    participant Admin as Admin Interface
    participant Geo as Geo Profile Service
    participant User as User Service

    Admin->>Geo: Apply approved declared_country change
    Geo->>Geo: Create new version record
    Geo->>User: Sync current declared_country
    alt Sync succeeds
        User-->>Geo: OK
        Geo->>Geo: Mark version as applied
        Geo-->>Admin: Success
    else Sync fails
        User-->>Geo: Error
        Geo->>Geo: Mark version as sync_failed
        Geo-->>Admin: Failure
    end
```

## Integration with User Service

`User Service` keeps the latest effective `declared_country` because other services and the gateway may need it frequently for response shaping without querying Geo Profile Service.

Integration rules:

- Geo Profile Service owns the mutation workflow.
- `User Service` stores only the latest effective value.
- Reads of the current country for normal business responses should go to `User Service`.
- Reads of country history and geo-derived data should go to Geo Profile Service.

## Integration with Auth / Session Service

Geo Profile Service must be able to request blocking of suspicious sessions.

Contract assumptions:

- Blocking is idempotent.
- The block applies to `device_session_id`, not to the entire user account.
- The effect is expected on subsequent requests, not the current triggering request.

This keeps the hot path simple and avoids synchronous enforcement coupling.

## Integration with Mail Service

Mail notifications are optional and configuration-driven.

Mail is sent only when:

- `country_review_recommended` transitions to `true`
- Email notifications are enabled

Mail is auxiliary and must not be required for business correctness.

## Event Bus Integration

The service emits an event when `country_review_recommended` transitions to `true`.

Event usage:

- Auxiliary notification for downstream systems
- Reduced delay for admin workflows
- Optional future fan-out for additional internal consumers

Important constraint:

- The event bus is not the source of truth.
- Loss of an event must not lose the business state.
- Periodic pull through the service API must remain sufficient to recover missed notifications.

## Failure and Degradation Model

The service is intentionally designed for fail-open behavior relative to the edge.

### Edge-to-Service Failure

If Geo Profile Service is unavailable:

- `Edge Service` must continue request processing unchanged.
- The publication failure becomes a metric/logging concern.
- No user-visible request rejection is introduced by this dependency.

### In-Service Processing Failure

If the worker pipeline temporarily fails:

- Already accepted observations stay queued if a durable queue is used.
- Processing lag grows and must be monitored.
- Administrative state may become stale, but the rest of the platform keeps functioning.

### User Service Sync Failure

If `declared_country` sync to `User Service` fails:

- The version record remains in Geo Profile Service.
- The version must be marked as not yet effective.
- Retry or operator action can be used later.
- No silent divergence is allowed.

### Mail or Event Delivery Failure

If mail or event publication fails:

- The failure is logged and metered.
- `country_review_recommended` remains persisted.
- Administrative polling can still find the affected user.

## Privacy and Retention Posture

The privacy posture is intentionally minimal.

- Do not store raw IP long-term unless a later justification appears.
- Prefer storing country-level derived facts and aggregates.
- If hashed or obfuscated IP is introduced later, treat it as an implementation detail, not as a core domain dependency.
- Retention is expected to be bounded and configurable.

## Operational Observability

The service should expose metrics and logs for at least:

- Ingest acceptance rate
- Ingest publish failures observed by edge
- Queue depth
- Queue lag
- Geo-IP lookup latency
- Observation processing latency
- Review flag transitions
- Suspicious session block commands
- User Service sync failures
- Mail send failures
- Event publication failures

The service must be easy to operate even though it does not sit on the synchronous business-critical path.

## Minimal Initial API Surface

The initial required API surface is intentionally small.

Binary ingest path:

- Asynchronous FlatBuffers message publication from edge
- No business response body
- No synchronous decision returned to edge

Internal JSON REST paths:

- List review candidates by filter
- Read user geo profile grouped by `device_session_id`
- Apply approved `declared_country` version change
- Optional internal health and metrics endpoints

Any additional endpoints should be added only if a concrete consumer appears.

## Design Trade-Offs Accepted by This Architecture

This architecture intentionally accepts the following trade-offs:

- Some observation messages may be lost if the service is down and the edge cannot deliver them.
- The request that triggers suspicious-session detection is allowed to continue.
- Geo-IP history is not strictly reproducible against past database versions.
- Current `declared_country` is denormalized into `User Service`.
- Administrative approval policy stays flexible and human-driven.

These trade-offs are acceptable because they keep the hottest path simple while preserving enough internal state for review and risk handling.

## Implementation Readiness Statement

The architecture is considered ready for implementation planning.

The main remaining work is not conceptual but executional:

- Precise API shape
- Queue implementation details
- Scoring formula tuning
- Suspicious-session thresholds
- Concrete storage schema
- Operational hardening