Sankhya

Internal AI operations workspace for authenticated support chat, document ingestion, admin observability, and Gemini-powered responses with persistent state.

Description Sankhya is a production-style AI support console. Users sign in with seeded local identities, open a live chat workspace, stream answers from Gemini over SSE, persist conversations in PostgreSQL, and manage privileged operations through an admin dashboard protected by RBAC, session-backed auth, and audit logging.

---

What This Actually Does

Sankhya is not just a chat page. It is a full-stack internal operations product that combines:

• a user workspace for authenticated AI conversations
• a FastAPI backend for chat orchestration, persistence, security, and metrics
• a PostgreSQL data layer for users, conversations, messages, auth sessions, token usage, and audit logs
• an admin console for metrics, document ingestion, and operational visibility
• a Gemini integration for text generation and embeddings
• an optional Redis-backed queue path for background embedding and tool workflows

In practice, this means you can:

• sign into the main app as a user
• send a prompt and watch the answer stream live
• come back later and see persisted conversation history
• sign into the admin area as an admin
• ingest documents into the system
• inspect token usage, queue depth, and audit-aware operational views

Why It Is Strong

The current repository is stronger than a typical demo because it already includes:

• session-backed login instead of anonymous chat access
• role-based access control for privileged routes
• audit logging for sensitive actions like login, logout, admin reads, and document creation
• durable storage for conversations, messages, token usage, auth sessions, and metrics
• SSE streaming for a responsive operator experience
• graceful degradation when Redis-backed embedding queue infrastructure is unavailable locally
• a monorepo structure that keeps UI, API, workers, models, and docs aligned

This makes Sankhya a good base for:

• internal support copilots
• operations assistant dashboards
• retrieval-enabled service tools
• secure local demos of a production-style AI product

What You Will See

User Workspace

Open http://localhost:3000.

You will see:

• a sign-in panel for the user workspace
• a conversation sidebar
• a live message area
• a streaming composer that sends prompts to the backend over SSE

After login, the UI automatically uses the session token returned by /api/v1/auth/login.

Admin Dashboard

Open http://localhost:3000/admin.

You will see:

• an admin sign-in form
• dashboard metrics
• document ingestion controls
• token usage data
• system log views

Admin-only endpoints are protected by RBAC permissions, and sensitive actions are recorded in the audit log.

API Surface

Open http://localhost:8000/docs.

You can inspect and test:

• /api/v1/auth/login
• /api/v1/auth/me
• /api/v1/auth/logout
• /api/v1/chat/stream
• /api/v1/conversations/{user_id}
• /api/v1/admin/dashboard
• /api/v1/admin/audit-logs

Product Screens

These screenshots are taken from the current local build and show the live UI after the latest auth, RBAC, and admin updates.

1. Authenticated Chat Workspace

This is the main operator view after session login. It shows the signed-in identity, active conversation history, and a live streamed assistant response in progress or already persisted.

Why it matters:

• proves the user session is active
• shows the actual chat surface people will use every day
• demonstrates conversation persistence and streamed response rendering in the same screen

2. Admin Dashboard Overview

This is the top-level admin surface after an admin signs in. It highlights the role-aware session, granted permissions, and the operational summary cards used to monitor platform health.

Why it matters:

• shows that admin access is not anonymous anymore
• makes the RBAC model visible through the permission badges
• gives operators a quick read on platform-level usage and queue state

3. Token Usage Analytics

This view focuses on model usage records coming from the backend. It helps explain that Sankhya is not only a chat frontend, but also an observable AI system with latency and token reporting.

Why it matters:

• surfaces real Gemini usage information
• helps teams understand performance and cost patterns
• supports admin-side operational review

4. Document Ingestion and Indexed Content

This admin view shows how documents are created and tracked through the retrieval pipeline. The form on the left queues ingestion, and the table on the right shows the indexed document inventory and status.

Why it matters:

• shows the retrieval side of the platform, not just chat
• demonstrates a privileged write flow protected by admin permissions
• makes the RAG/document pipeline visible to reviewers and operators

Architecture

1. Platform Overview

This component diagram shows the current runtime boundaries, including the new session auth and audit path.

2. Auth, RBAC, and Audit Flow

This sequence view explains how login, permission checks, session resolution, and audit logging work together.

3. Live Chat Workflow

This sequence diagram captures the main user action: authenticated streaming chat from UI to Gemini and back.

4. Deployment Topology

This deployment view shows the local stack and the boundaries between frontend, backend, Postgres, Redis, and Gemini.

5. Domain Model

This domain view includes the latest persisted control-plane objects such as auth_sessions and audit_logs.

End-to-End Workflow

User Path

1. A user signs in with email + api_key.
2. The backend verifies the credentials against the users table.
3. A session token is issued and stored in auth_sessions.
4. The frontend stores that session token in browser session storage.
5. The user sends a prompt.
6. The backend resolves the principal, checks access scope, and streams the answer over SSE.
7. Conversation history and token usage are persisted in PostgreSQL.

Admin Path

1. An admin signs in with an admin identity.
2. The backend issues a session and permission-aware principal.
3. Admin-only endpoints require permissions such as admin:access, documents:write, and audit:read.
4. Sensitive actions are written to audit_logs.
5. The admin can inspect metrics, queue status, and privileged views from the dashboard.

Repository Layout

.
|-- .env.example
|-- docker-compose.yml
|-- README.md
|-- docs
|   `-- diagrams
|-- backend
|   |-- Dockerfile
|   |-- requirements.txt
|   |-- alembic.ini
|   |-- alembic
|   |-- scripts
|   `-- app
`-- frontend
    |-- Dockerfile
    |-- package.json
    |-- app
    |-- components
    |-- hooks
    `-- lib

Core Areas

• backend/app/api FastAPI route composition for auth, chat, conversations, documents, admin, and health endpoints.

• backend/app/core Configuration, structured logging, runtime validation, request IDs, and security helpers.

• backend/app/models SQLAlchemy entities for users, conversations, messages, token usage, auth sessions, audit logs, metrics, and queue tasks.

• backend/app/services Gemini integration, audit logging, agent orchestration, queueing, metrics, memory, and retrieval services.

• backend/app/repositories Database access boundaries for conversations, tasks, and documents.

• backend/app/workers Background processing entry points for embedding and tool-task execution.

• frontend/app Next.js App Router pages for user and admin experiences.

• frontend/lib API helpers, SSE streaming helpers, and the new login/session client.

Local Setup

1. Prepare Environment Files

Copy-Item .env.example .env
Copy-Item backend\.env.example backend\.env

2. Configure Required Services

Minimum local setup:

• PostgreSQL on localhost:5432
• Node.js for the frontend
• Python for the backend
• a valid Gemini API key in backend/.env

Optional but recommended:

• Redis on localhost:6379

3. Apply Migrations and Seed Users

cd backend
python -m alembic upgrade head
$env:PYTHONPATH='.'
python scripts\seed.py

The seed script creates or updates:

• demo@sankhya.local
• admin@sankhya.local

If a user does not already have an API key, the script prints it to the console. If the users already exist, their API keys remain in the database.

4. Start the Backend

cd backend
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

5. Start the Frontend

In a second terminal:

cd frontend
npm install
npm.cmd run dev

How To Use It Properly

User Login and Chat

1. Open http://localhost:3000
2. Sign in with:
   • email: your seeded user email
   • api key: the API key stored for that user
3. Choose a conversation or start a new one
4. Send a support-style prompt
5. Watch the response stream into the chat area

Admin Login and Operations

1. Open http://localhost:3000/admin
2. Sign in with the seeded admin account
3. Review dashboard metrics
4. Create a document from the document manager
5. Inspect token usage and system logs
6. Query audit activity through /api/v1/admin/audit-logs

How To Inspect Seeded API Keys

If the seed script does not print keys because the users already exist, inspect the current local DB values directly:

select email, api_key
from users
where email in ('demo@sankhya.local', 'admin@sankhya.local');

This is meant for local development only. In a production deployment, do not expose or document secrets this way.

Service Endpoints

• Frontend: http://localhost:3000
• Admin: http://localhost:3000/admin
• FastAPI docs: http://localhost:8000/docs
• Backend root: http://localhost:8000
• Health live: http://localhost:8000/api/v1/health/live
• Health ready: http://localhost:8000/api/v1/health/ready

Environment Reference

Root .env

• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD
• POSTGRES_PORT
• REDIS_PORT
• BACKEND_PORT
• FRONTEND_PORT
• GEMINI_API_KEY
• GEMINI_MODEL
• GEMINI_EMBEDDING_MODEL
• APP_ENV
• LOG_LEVEL

Backend .env

• APP_DATABASE_URL
• APP_REDIS_URL
• APP_GEMINI_API_KEY
• APP_GEMINI_MODEL
• APP_GEMINI_FALLBACK_MODEL
• APP_GEMINI_EMBEDDING_MODEL
• APP_RATE_LIMIT_REQUESTS
• APP_RATE_LIMIT_WINDOW_SECONDS
• APP_MAX_AGENT_STEPS
• APP_MAX_TOOL_WAIT_SECONDS
• APP_EMBEDDING_DIMENSION
• APP_CORS_ORIGINS
• APP_SSE_HEARTBEAT_SECONDS
• APP_AUTH_SESSION_TTL_HOURS

Security and Control Plane

What is implemented now:

• session-backed login
• RBAC permissions mapped by role
• tenant-aware conversation access
• admin-only document and audit routes
• persisted audit logs
• request IDs and structured logging
• security headers and fail-fast runtime checks

What still strengthens it further:

• replace plaintext API-key login with password-based auth or external identity
• hash stored login secrets instead of storing raw API keys
• rotate keys automatically
• install Redis locally for the full queue path
• add persisted audit log views directly in the admin UI

Operational Notes

• If Redis is unavailable locally, the app still runs, but queue-backed background work degrades.
• If APP_GEMINI_API_KEY is missing, chat can fall back instead of returning a live Gemini answer.
• If you change database schema or auth behavior, rerun migrations before testing the UI.

Why This Repo Is A Strong Base

Sankhya is already structured like a serious internal platform:

• the security model now covers login, session identity, permissions, auditability, and scoped access
• the product experience spans both end-user chat and admin operations
• the data model supports future reporting, retention, and governance work
• the architecture is ready for additional hardening in workers, observability, and production deployment

That makes it useful both as:

• a working local product
• a showcase of full-stack AI product engineering
• a foundation for a more production-hardened enterprise assistant

License / Usage

This repository is currently documented as an implementation-oriented project workspace. Add an explicit license and contribution policy before public distribution.