galaxy-game/geoprofile

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

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.

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.

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.

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.

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.

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