Star — Architecture & Flows Explorer

Strict Tenant Separation

Tenants are kept completely separate at the database connection level. There is zero overlapping namespace or cross-contamination, guaranteeing that customers cannot see each other's data at all.

Hallucination Mitigation

The AI chatbot does not answer questions from generic training data. It searches and retrieves facts directly from your verified corporate PDFs, quoting the exact document revision.

Zero-Trust Security Gating

Each retrieval step checks permissions dynamically. High-level security gates guarantee the AI only sees and processes context the user's role is explicitly authorized to view.

Audit Logs & Compliance

Every transaction, RAG lookup, and manager approval leaves a permanent, encrypted audit trail in high-performance query storage (Audit Store) for full forensic compliance.

Core Business Lifecycles

End-to-End Leave Workflow

Coordinates the full leave request cycle. Employees can check balances and request time off using natural language. The system identifies reviewer structures, routes approvals to managers, and securely updates database quotas once confirmed.

Performance Appraisal Management

Orchestrates reviews across the organization. It manages evaluation templates, self-assessments, and reviewer feedback, enforcing security policies so peer ratings are strictly visible only to authorized review partners.

Smart Policy Search

When employees ask about company guidelines, the system securely searches verified company documents to find exact matching rules (like resignation notice periods or holidays) and translates them into simple, clear answers.

Audited Contract Access

When employees ask to search or view their own employment contracts, the system verifies user permissions, locks down access strictly to the owner's record, and logs a permanent audit entry to track the transaction.

Governance and Security Mandate

The Star architecture incorporates **Zero-Trust Tool Scoping**. Under no condition does the AI agent make database modifications without matching preset permissions or explicit confirmation logic. All operational actions are logged for maximum visibility.

1. Chat Request & Tool Lifecycle Sequence

Sequence diagram illustrating client authentication, multi-tenant session translation, intent routing, tool gating, and database writes.

Click to Zoom Diagram

sequenceDiagram
    autonumber
    actor Client as Mobile & Web Client
    participant Router as API Gateway
    participant Service as Chat Orchestrator
    participant AuthCtx as Auth Context Builder
    participant DB as Tenant Database
    participant HybridRouter as Hybrid Intent Router
    participant PolicyService as Tool Gating Engine
    participant AI as AI Gateway

    Client->>Router: POST /chat { messages } (Bearer JWT)
    Router->>Router: Verify JWT & extract claims
    Router->>Service: chat(request, current_user)
    Service->>AuthCtx: build_chat_auth_context()
    AuthCtx->>DB: Query profile, presets & permissions
    DB-->>AuthCtx: Raw database records
    AuthCtx-->>Service: ChatAuthContext (permission_codes, relationships)
    Service->>HybridRouter: route(message, history, permission_codes)
    HybridRouter-->>Service: ChatRoute(domain, action_stage, target_scope)
    Service->>PolicyService: Filter accessible tools
    PolicyService-->>Service: List of accessible tools
    Service->>AI: call_ai(messages, accessible_tools)
    AI-->>Service: Tool call requests (submit_leave, etc)
    Service->>DB: Execute actions (bound strictly to tenant schema)
    DB-->>Service: Status / Write confirmation
    Service-->>Router: ChatResponse
    Router-->>Client: HTTP 200 OK (ChatResponse)

2. Document Ingestion & RAG Retrieval Pipeline

How policy files are processed and retrieved through a simplified 5-stage Query Understanding and Planning Pipeline.

flowchart TD
    %% Node Style Definitions
    classDef default fill:#0f172a,stroke:#1e293b,stroke-width:1px,color:#cbd5e1,font-family:Inter,font-size:10px;
    classDef inputNode fill:#0c4a6e40,stroke:#0ea5e9,stroke-width:1.5px,color:#f8fafc,font-family:Inter,font-weight:bold,font-size:10px;
    classDef outputNode fill:#064e3b40,stroke:#10b981,stroke-width:1.5px,color:#f8fafc,font-family:Inter,font-weight:bold,font-size:10px;

    subgraph Ingestion["Ingestion Pipeline"]
        Doc["PDF / Docx Ingestion"]:::inputNode --> Parser["Structure Parser"]
        Parser --> Chunker["Chunker and Metadata Tagging"]
        Chunker --> Embed["Vector Embeddings Generator"]
        Embed --> VectorDB["Tenant Vector Document Store"]:::outputNode
    end

    subgraph RAG["Query and RAG Planning"]
        UserQuery["User Question"]:::inputNode --> Analyzer["1. Query Analysis and Concept Expansion"]
        Analyzer --> Planner["2. Retrieval Plan and Validation"]
        Planner --> Searcher["3. Smart Vector Search and Deduplication"]
        Searcher --> Security["4. Row-Level Security Filtering"]
        Security --> Context["5. Grounded AI Context"]:::outputNode
    end

    %% Style Subgraphs
    style Ingestion fill:#1e293b15,stroke:#334155,stroke-width:1.5px,rx:12px,ry:12px;
    style RAG fill:#1e293b15,stroke:#334155,stroke-width:1.5px,rx:12px,ry:12px;

    %% Style Links
    linkStyle default stroke:#0ea5e9,stroke-width:1.5px,opacity:0.75;

1. Query Analysis

Analyzes the user's question, extracts core concepts, and expands terms (e.g. mapping 'resign' to 'resignation notice') to capture natural phrasing.

2. Retrieval Plan

Builds a search blueprint deciding which directories to query, then validates inputs to ensure requests comply with database boundaries.

3. Vector Search

Queries semantic vector indexes, aggregates matching paragraph fragments from company files, and filters duplicates.

4. Security Filtering

Passes retrieved segments through dynamic permission policies (e.g. Employee vs HR Admin presets), filtering unauthorized chunks out.

5. Grounded Context

Feeds only the verified, safe, and authorized text fragments to the AI model to generate a hallucination-free response citing exact revisions.

3. Multi-Tenant Database Isolation Engine

How dynamic connection routing ensures strict database separation between corporate tenants.

Dynamic Connection Isolation

Instead of filtering database rows using conditional WHERE tenant_id = 'company' filters (which are prone to developer omission and leaking vulnerabilities), data isolation is enforced at the database connection layer itself.

Each customer tenant's records live inside an independent, fully isolated database namespace. When a request is verified, a lightweight branched database engine is spawned specifically for that tenant, translating all database query instructions to execute exclusively within their isolated context. Tenants have no access to, or visibility of, other tenant spaces.

Engine Schema Translation Map

The database adapter intercepts statements at the connection pool level, dynamically mapping generic table queries to isolated tenant schemas.

app/db/session.py

def make_tenant_session(tenant_id):
  schema = _safe_schema_name(tenant_id)
  # Configure connection session with dynamic schema mapping
  tenant_connection = db_connection.configure_session(
    schema_translate_map={"tenant": schema}
  )
  return tenant_connection.open_session()

4. Role Scoping & Permission Catalogue

Click on a system role preset on the left to see its default permission codes highlight in the security grid on the right.

1. Select System Preset

2. Scoped Permission Codes

⚙️ General & System

can_use_chat

Access the AI assistant interface.

can_view_admin_hub

Access main administrator console.

can_view_audit_logs

Examine transaction and audit logs.

can_manage_roles_permissions

Edit system role mappings and presets.

👥 HR & Team Scope

can_manage_team

Access direct reports and reviewer details.

can_manage_employees

Maintain global user profiles.

can_manage_users

Deactivate accounts or provision credentials.

can_view_hr_reports

Access high-level workforce metrics.

📈 Performance Cycles

can_manage_performance_cycles

Initialize appraisal timelines.

can_manage_cycle_eligibility

Configure review relationships.

can_view_performance_reports

View performance appraisal analytics.

📄 Documents & Contracts

can_manage_policy_documents

Modify policy manuals stored in Vector Store.

can_manage_contract_documents

Upload contract versions to Vector Store.

can_view_employee_contracts

Browse sensitive employment agreements (audited).

📅 Leave & Time Operations

can_approve_leave

Approve or reject leave logs.

can_manage_leave_balances

Modify base quotas or carryovers.

Architecture & Flows Explorer

Live Request Flow Simulator