ADMIN — SYSTEM ADMINISTRATION

The control center of the entire ERP. User identities, permissions, authentication, printer hardware, print queue monitoring, AI assistant configuration, and activity auditing — everything that keeps the system secure, configured, and observable.

February 2026 • Solen Kablo • Living Document

1. WHAT ADMIN DOES

The Admin module answers six questions that the entire ERP system depends on:

1.1 The Three User Types

The system recognizes three fundamental user types, each with a different scope of access and a different physical context of use:

1.2 The Hybrid Permission Model

The permission system operates at two layers simultaneously:

Both layers coexist through a backward-compatible function called check_permission_smart. It first checks the legacy role-based system, then falls back to the granular JSON system. Super admins bypass both — they always pass.

1.3 Beyond User Management

Admin is not just about users. It is the only module that manages physical hardware (network printers on the factory floor), provides real-time operational monitoring (print queue dashboard), and controls the AI assistant that other users interact with. It is also the only module that writes to the user_activity_logs table, creating an audit trail of every administrative action taken in the system.

2. THE DATA FLOW

Admin’s data flows are fundamentally different from production modules like Hammadde or Teknik. Those modules have a linear pipeline (supplier → order → entry → inventory). Admin has a hub-and-spoke pattern: it sits at the center and every other module depends on it.

2.1 Authentication Flow

Every subsequent API call across the entire system carries the JWT access token in the Authorization: Bearer header. The token contains the user’s ID, username, user_type, and permissions — meaning every route in every module can verify identity and check permissions without an extra database query.

2.2 Permission Enforcement Flow

On the frontend, the same check runs proactively: routes are hidden from the menu, buttons are disabled or invisible, and entire pages redirect to the user’s allowed dashboard if they attempt direct URL access.

2.3 Print Job Flow

Print jobs are created by other modules (Material Entry prints QR labels after recording a delivery, Materials List reprints labels on demand) but the queue itself lives in Admin. The Print Job Monitor gives super admins a real-time view of all jobs across all four factory printers, with the ability to retry failed jobs or cancel queued ones.

2.4 AI Interaction Flow

Every AI interaction is comprehensively logged: the user’s query, detected language, AI model used, reasoning steps, tool calls, API responses, timing metrics, and security flags. This creates a complete forensic trail of what the AI did and why.

2.5 The Hub-and-Spoke Dependency

3. THE DATABASE LAYER

The Admin module owns 10 database tables, more than any other module. These tables fall into four groups: identity, sessions, hardware, and auditing.

3.1 Identity Tables

3.2 Session Table

Sessions are not just for token validation. They provide a complete login history: which device was used, from which IP, when they logged in, when they logged out (or if the session expired). The cascade delete on the users relationship means deleting a user automatically purges all their sessions.

3.3 Hardware Tables

3.4 Audit Tables

3.5 Entity-Relationship Summary

4. THE BACKEND ARCHITECTURE

The Admin backend is organized into five route groups, one core service, one security module, and a permission utility layer. Unlike production modules that have a single route file, Admin spans multiple files because its concerns are fundamentally different from each other.

4.1 Route Groups

4.2 Authentication Endpoints (5)

4.3 User Management Endpoints (9)

4.4 Printer & Print Queue Endpoints (10)

4.5 AI Endpoints (12)

4.6 Core Services

AuthenticationService

The central authentication engine. Handles five operations:

• authenticate_user — Finds user by username or email, verifies password with bcrypt, updates last_login timestamp.
• create_user_session — Generates JWT access and refresh tokens. Critical detail: operator accounts get 6-month token expiry (for kiosk phones that shouldn’t require re-login), while all other accounts get the standard 12-hour expiry.
• get_user_by_token — Decodes JWT, validates expiry, checks that user still exists and is active.
• logout_user — Terminates session record, stamps logout time.
• refresh_token — Validates refresh token, issues new access token without creating a new session.

SecurityManager

Low-level cryptographic operations: bcrypt password hashing and verification, JWT creation with configurable expiry, JWT decoding with signature verification, and token expiry validation. Uses HS256 algorithm with a configurable secret key.

Permission Utilities

Four functions that form the permission checking backbone used by every module in the system:

• is_permitted_user(user, required_types) — Legacy role check. Super admin always passes.
• check_user_permission(user, page_id, button_id) — Granular JSON permission check. Parses the user’s permissions field, navigates to pages[page_id].buttons[button_id].
• has_special_permission(user, permission) — Checks special flags like hard_delete or manage_users.
• check_permission_smart(user, required_types, page_id, button_id) — The unified entry point. Tries role-based first, then granular. This is what most routes actually call.

4.7 FastAPI Dependencies

Admin defines four injectable dependencies that every module in the system imports:

5. THE FRONTEND

The Admin frontend consists of five distinct pages plus a cross-cutting permission layer that affects every page in the entire application.

5.1 Page Inventory

All four admin pages sit under the /admin route prefix and share the canAdmin access guard, which restricts visibility to super admin users. The Login page is the only public page in the entire application.

5.2 The Permission Layer (Cross-Cutting)

Admin’s most impactful frontend contribution isn’t its own pages — it’s the permission infrastructure that every other page uses. This lives in three files:

5.3 Login Page

The login page handles three scenarios:

1. Standard login: Username/password form with “Remember me” checkbox. Stores JWT tokens and user data in localStorage (solen_auth_token, solen_refresh_token, solen_current_user).
2. Kiosk auto-login: Detects the Fully Kiosk Browser via user agent string. When detected, automatically logs in as the operator account and redirects to /production. No human interaction required.
3. Secret URL token: Accepts ?kiosk=SOLEN_FACTORY_2024_KIOSK_SECRET as a URL parameter to trigger auto-login from any browser. This is a factory-floor convenience for mounting new kiosk devices.

5.4 User Management Page

The most complex page in the Admin module. It provides a full CRUD interface for user accounts with a three-tab modal:

• Tab 1 — Temel Bilgiler (Basic Info): Username, email, full name, user type (dropdown with super_admin, lab_user, operator, teknik_user, bakim_user, and custom types), status, password (for new users), force_password_change toggle.
• Tab 2 — Yetkiler (Permissions): The granular permission editor. Renders the full permission manifest as a tree: each page is a switch (access on/off), and under each page, individual buttons are checkboxes. Includes four quick-fill templates: Full, Empty, Operator Default, Lab User Default.
• Tab 3 — Önizleme (Preview): Shows a read-only summary of what the user will be able to access after saving — which modules, which pages, which buttons.

Beyond the modal, the page provides: search across username/email/full_name, filter by user_type and status, password reset (generates and displays new password), suspend/activate toggle, delete with confirmation, and last login display with Turkey/Istanbul timezone conversion.

5.5 Printer Management Page

CRUD interface for factory label printers. Each printer has: name, description, IP address, port, location, status, and assigned materials (multi-select from material types: raw_copper, raw_tin, raw_plastic, etc.). Includes a “Test Connection” button that hits the backend’s /printers/{id}/test endpoint to verify the printer is reachable on the network.

5.6 Print Job Monitor Page

Real-time monitoring dashboard. Top section shows four statistics cards: Queued (blue), Printing (orange), Completed (green), Failed (red). Below is a ProTable showing all print jobs with columns: QR code, material type, lot number, supplier, printer, status, requested by, requested at, completed at, error message. Supports retry (requeues failed jobs) and cancel (removes queued jobs). All timestamps are Turkey/Istanbul timezone.

5.7 AI Settings Page

Four-tab configuration interface:

• Overview: AI status (active/inactive), today’s query count, total queries, average response time, success rate visualization, and a connection test button.
• API Keys: Save, test, and delete API keys for three providers (Gemini, OpenAI, Anthropic). Keys are masked in the UI and stored in the server’s .env file.
• Model Settings: Enable/disable AI, select model (cascader grouped by provider: Gemini 3 Flash/Pro, GPT-5.2/Mini, Claude Sonnet/Opus/Haiku), configure max tokens (1024–8192) and temperature (0.1–0.9).
• Audit Log: Full history of AI interactions. ProTable with expandable rows showing the original query and AI response. Filterable by user, tool, status, IP address. Includes response time metrics.

5.8 Common Frontend Patterns

5.9 The API Layer

The frontend communicates with the backend through a centralized API utility (src/utils/api.ts) that dynamically resolves the backend URL based on the deployment context:

• HTTPS mode: Uses /api proxy (reverse proxy handles routing).
• HTTP localhost: http://localhost:8000/api (development).
• HTTP local network: http://{hostname}:8000/api (factory LAN access).
• Custom override: window.BACKEND_URL for special deployments.

Every API call includes the Authorization: Bearer {token} header, retrieved from localStorage. The authentication service (src/services/realAuth.ts) provides login(), logout(), getCurrentUser(), and getToken() functions that all pages import.

6. THE SUBMODULES

The Admin module is organized into four submodules, ordered by operational flow: printers must be configured before print jobs can be monitored, AI settings stand alone, and user management governs access to everything.

6.1 Yazıcı Yönetimi (Printer Management)

6.1.1 Purpose and Business Context

Every raw material that enters the factory receives a printed A6 label with a QR code, weight, supplier, lot number, and entry date. These labels are the physical identity of the material — they’re scanned at every downstream station (lab testing, production, stock). The label printers are industrial network devices (TCP port 9100 / IPP port 631) placed in specific locations: the laboratory and three production lines. Printer Management is the registry where these physical devices are configured, tested, and assigned to material types.

Without this submodule, the system wouldn’t know where to send print jobs. It answers four questions: What printers exist? Where are they? Are they online? What material types can each printer handle?

6.1.2 Database Schema

Single table: printers (model file: 66 lines)

PrinterStatus Enum

class PrinterStatus(str, Enum):
    ONLINE      = "online"
    OFFLINE     = "offline"
    ERROR       = "error"
    MAINTENANCE = "maintenance"

Default Printers (Migration Seed Data)

6.1.3 API Contract — 5 Endpoints

6.1.4 CRUD Flow

Create:

1. Click “Yeni Yazıcı Ekle” button in toolbar
2. Modal (600px) opens with 7 fields: name (required), description, location, IP address (required), port (default 9100), assigned materials (multi-select: A=Bakır, B=Kalay, C=Plastik, D=Katalizör, E=Boya, F=Antirodent), status
3. On submit: POST /api/printers/create
4. Backend creates record with is_active=true, status=online, converts assigned_materials array to JSON string
5. On success: toast “Yazıcı ‘{name}’ eklendi” → modal closes → table reloads
6. Note: New printer requires application restart for its background print worker to initialize

Read:

1. Page loads → GET /api/printers/list
2. ProTable (11 columns) renders: ID, name, description, IP (blue tag), port, location, status (color-coded tag), assigned materials (letter tags), active (check/cross icon), actions
3. Client-side search filters across name, description, IP, location, status, port, and ID simultaneously

Update:

1. Click edit icon in Actions column
2. Same modal opens pre-filled with current values
3. Modify any fields → click “Güncelle”
4. PUT /api/printers/update/{id} → backend updates only provided fields, stamps updated_at
5. On success: toast “Yazıcı ‘{name}’ güncellendi” → modal closes → table reloads

Delete:

1. Click delete icon (danger button) in Actions column
2. Confirmation modal: “{name} yazıcısını silmek istediğinize emin misiniz?”
3. On confirm: DELETE /api/printers/{id}
4. Backend checks for pending print jobs (QUEUED or PRINTING status)
5. If pending jobs exist: deletion blocked with error “Bu yazıcının {n} bekleyen işi var. Önce işleri tamamlayın veya iptal edin.”
6. If no pending jobs: printer deleted → toast → table reloads

Test Connection:

1. Click test icon (ApiOutlined) in Actions column
2. POST /api/printers/{id}/test
3. Backend calls PrintService.test_printer_connection() which executes lpstat -p {printer_name} via subprocess
4. Possible results: “connected” (idle), “busy”, “not_found”, “timeout”, “error”
5. Backend updates printer.status (ONLINE or OFFLINE) and stamps last_checked
6. On success: toast with printer name → table reloads (status column reflects new state)
7. On failure: warning message → table reloads (status shows “Çevrimdışı” in red)

6.1.5 The Print Service — Label Generation Engine

File: app/services/print_service.py (576 lines). This is the core service that generates and prints A6 labels.

Label Specifications

Label Content Layout

1. Centered QR code (300px) with QR text below
2. Lot number (if exists)
3. Weight (kg)
4. Material type / product name
5. Date and time (Turkey timezone)
6. “Created by” user name
7. Notes (if exists)

Key Service Methods

Font Fallback Chain

The service tries fonts in platform order: macOS (/System/Library/Fonts/) → Linux (/usr/share/fonts/) → Windows (C:/Windows/Fonts/) → PIL default. This makes label generation work across all development and production environments.

6.1.6 The Print Worker — Background Job Processing

File: app/services/print_worker.py (292 lines). Each active printer gets a dedicated background worker thread.

Architecture

Worker Lifecycle

1. Init: Generates CUPS printer name from IP (e.g. Printer_192_168_0_182), ensures printer is registered in CUPS via lpadmin, sets A6 as default media via lpoptions
2. Poll loop: Every 1 second, queries DB for next QUEUED job for this printer (ordered by requested_at — FIFO)
3. Process job: Sets status to PRINTING → stamps started_at → fetches material + user data → calls print_label_with_quantity()
4. On success: Status → COMPLETED, stamps completed_at
5. On failure: If retry_count < 3: increment, set back to QUEUED. If retry_count ≥ 3: status → FAILED

CUPS Auto-Registration

When a worker starts, if the printer isn’t registered in CUPS, the worker automatically adds it:

# Auto-register printer in CUPS
lpadmin -p Printer_192_168_0_182 -E -v ipp://192.168.0.182:631/ipp/print -m everywhere
lpoptions -p Printer_192_168_0_182 -o media=A6

6.1.7 Material Assignment System

Each printer can be assigned specific material types via the assigned_materials JSON array. The six material type codes map to the factory’s QR code letter system:

The Lab printer (ID 1) is assigned all six types since it handles all material entries. Production printers have empty assignments — they are used for production-stage labeling.

6.1.8 Frontend Architecture

Single file: src/pages/Admin/PrinterManagement/index.tsx (527 lines). Route: /admin/printer-management.

Component Structure

Client-Side Search

The search input filters across all visible columns simultaneously: name, description, IP address, location, status (both English and Turkish terms), port, and ID. This is pure frontend filtering — the full dataset is always fetched.

No WebSocket Integration

Unlike other modules, Printer Management does not use WebSocket for real-time updates. Table refreshes happen via manual actionRef.current?.reload() after each mutation (create, update, delete, test).

6.1.9 Permission Model

Page ID: admin.yazici_yonetimi

Backend enforces role-based: only super_admin can create/update/delete, super_admin + lab_user can test. Frontend registers these 7 granular permissions in buttonRegistry for the permission editor to discover.

6.1.10 How Printer Management Connects to the Rest of the System

6.2 Yazdırma İzleme (Print Job Monitor)

6.2.1 Purpose and Business Context

Every material label print passes through a job queue. The job is created the moment a user clicks “Yazdır” in Material Entry or Materials List, and a background worker picks it up within one second. Yazdırma İzleme is the real-time dashboard that makes this invisible pipeline visible: how many jobs are waiting, which are printing right now, which succeeded, which failed, and why.

It serves two purposes: monitoring (are the printers keeping up? any failures?) and intervention (retry a failed job, cancel a queued one). Without this submodule, a failed print would silently vanish after 3 retries, and nobody would know a material is missing its label.

6.2.2 Database Schema

Single table: print_jobs (model file: 69 lines)

PrintJobStatus Enum (5 states)

class PrintJobStatus(str, Enum):
    QUEUED    = "queued"      # Waiting in queue
    PRINTING  = "printing"    # Worker is printing now
    COMPLETED = "completed"   # Label printed successfully
    FAILED    = "failed"      # Failed after 3 retries
    CANCELLED = "cancelled"   # Manually cancelled by admin

Job Lifecycle

Denormalization Strategy

Three columns (material_type, lot_number, supplier_name) are deliberately denormalized from raw_materials and suppliers. This allows the monitoring dashboard to display all job data without expensive joins across tables — critical for a page that lists up to 500 jobs.

6.2.3 API Contract — 5 Endpoints

6.2.4 CRUD Flow

Create (Queue a Print Job):

1. In Materials List, click the print icon on a material row (disabled for palettes/reels)
2. Printer selection modal opens showing: QR code, label count (material.quantity or 1), and a dropdown of active printers fetched from GET /api/printers/list?active_only=true
3. Select printer → click “Yazdır”
4. POST /api/print-queue/queue/{material_id}?printer_id=X
5. Backend validates material exists, gets supplier name from relationship, checks if material is rejected (appends “ - REDDEDILDI” to QR), denormalizes type/lot/supplier into the job row
6. On success: toast “Yazdırma işi kuyruğa eklendi (#123)” → modal closes
7. Background worker picks up the job within 1 second and starts printing

Read (Monitor Jobs):

1. Navigate to /admin/print-monitor
2. Page loads → GET /api/print-queue/jobs?limit=200 + GET /api/print-queue/stats
3. 4 stat cards render at the top: Bekleyen (gray), Yazdırılıyor (blue), Tamamlanan (green), Başarısız (red)
4. ProTable (16 columns) renders all jobs with: ID, QR code (blue tag), material type (color-coded Turkish tag), lot, supplier, printer (filterable 1–4), copies (bold), status (color-coded tag), retry count (X/3 warning tag if > 0), error message (red with tooltip), user, requested/started/completed timestamps (Turkey timezone), duration (seconds), actions
5. Client-side search filters across QR code, lot, supplier, user, status, material type, ID, and printer — including Turkish translations

Retry (Failed → Queued):

1. Retry button (RedoOutlined) appears only on rows with status “failed”
2. Click retry → POST /api/print-queue/jobs/{id}/retry
3. Backend resets: status → QUEUED, retry_count → 0, clears error_message, nulls started_at and completed_at
4. On success: toast “İş #{id} tekrar kuyruğa eklendi” → table + stats reload
5. Worker re-picks the job on next poll cycle (within 1 second)

Cancel (Queued → Cancelled):

1. Cancel button (CloseCircleOutlined, danger) appears only on rows with status “queued”
2. Click cancel → confirmation modal: “İş #{id} iptal edilsin mi?” with “İptal Et” (danger) / “Vazgeç”
3. On confirm: DELETE /api/print-queue/jobs/{id}
4. Backend validates job is not PRINTING (blocks with “Devam eden iş iptal edilemez”), sets status → CANCELLED, stamps completed_at
5. On success: toast “İş #{id} iptal edildi” → table + stats reload

6.2.5 The Background Worker — How Jobs Actually Get Printed

The connection between this monitoring page and physical printing is the PrintWorker (292 lines, described in 6.1.6). Here’s the exact data flow when a worker processes a job:

The material_data Dict (Built by Worker)

Note the hybrid approach: some fields come from the denormalized job row (fast, no join), while weight, date, user name, and notes are fetched live from DB (always current).

Retry Logic (Automatic)

After the automatic 3 retries exhaust, the job shows as “Başarısız” with a retry count of “3/3” in the dashboard. An admin or lab user can then manually retry it (resetting the counter to 0).

6.2.6 Frontend Architecture

Single file: src/pages/Admin/PrintJobMonitor/index.tsx (509 lines). Route: /admin/print-monitor.

Component Structure

Date Formatting

All timestamps are stored as UTC in the database. The frontend converts them using dayjs.utc(dateStr).tz('Europe/Istanbul') and displays in D.MM.YYYY HH:mm:ss format (e.g. “18.02.2026 14:30:45”).

Material Type Tags (Color Mapping)

No WebSocket — Manual Refresh

Unlike other pages in the ERP, the Print Job Monitor does not use WebSocket for real-time updates. The table and stats refresh via actionRef.current?.reload() after mutations (retry, cancel) and on the table’s built-in reload button. There is no automatic polling.

6.2.7 Permission Model

Page ID: admin.yazdirma_izleme

Backend enforces: super_admin can do everything. lab_user can retry failed jobs. operator can only queue new jobs (via Material Entry) but cannot access the monitoring dashboard.

6.2.8 How Print Job Monitor Connects to the Rest of the System

6.3 AI Ayarları (AI Settings)

6.3.1 Purpose and Business Context

The ERP includes an AI assistant currently powered by Google Gemini via API integration (with OpenAI and Anthropic Claude fully integrated and ready). The assistant can answer questions about orders, materials, production, and inventory by calling internal APIs on behalf of users. AI Ayarları is the configuration and monitoring center for this assistant: API key management, model selection, parameter tuning, usage statistics, and a comprehensive audit trail of every AI interaction.

The current API-based integration is a fast-track demo layer — it provides immediate AI capabilities while the long-term vision develops in parallel. The roadmap is to build and deploy custom, locally-hosted models across the entire factory: production optimization, quality control, predictive maintenance, anomaly detection — essentially invisible AI agents that monitor and control everything constantly. For the language/search component specifically, a lightweight ~1B parameter model (such as Qwen or similar) will be fine-tuned for ERP-specific search query understanding, replacing the external API dependency entirely. The multi-provider architecture in this settings page was designed with this transition in mind — swapping from an external API to a local model endpoint is a configuration change, not a rewrite.

The AI agent itself lives in a separate service (solen_ai_service), external to the main backend. This submodule provides the control plane — the knobs and dashboards that let an administrator manage the AI without touching code or config files.

6.3.2 Database Schema — The 47-Column Audit Log

The AI system uses two tables for forensic-grade audit logging:

ai_audit_logs (47 columns)

Every single AI interaction is recorded with full context. The columns are organized into 8 groups:

11 indexes optimize queries: single-column on user_id, username, session_id, ip_address, selected_tool, success, created_at; composite on (user_id, created_at), (selected_tool, created_at), (success, created_at), (ip_address, created_at).

ai_audit_log_summaries (12 columns)

Daily aggregated statistics: total/successful/failed/blocked queries, unique users and IPs, top tools, top categories, average response times, error distribution. One row per day. Not currently exposed via API — reserved for future analytics dashboards.

6.3.3 API Contract — 12 Endpoints

6.3.4 CRUD Flow

Create / Update API Key:

1. Navigate to “API Anahtarları” tab → 3 provider cards (Google Gemini, OpenAI, Anthropic Claude) each with logo, status tag, and password input
2. Enter API key in the password field → click “Kaydet”
3. POST /api/ai/api-keys/save with { provider, api_key }
4. Backend validates: not empty, ≥ 20 chars, checks prefix (AIza for Gemini, sk- for OpenAI, sk-ant- for Anthropic — warning only, not blocking)
5. Writes to solen_ai_service/.env file, updates runtime os.environ, resets AI agent singleton
6. On success: toast “API anahtarı kaydedildi” + prefix warning if applicable → masked key shown on card → status refreshes

Read (Overview Dashboard):

1. Navigate to /admin/ai-settings → “Genel Bakış” tab loads
2. 4 stat cards: AI status (active/inactive), today’s queries, total queries, average response time
3. Success rate card with circular progress chart + successful/failed counts
4. Connection test card: shows status, API key status, current model. “Bağlantıyı Test Et” button calls GET /api/ai/status

Update Model Settings:

1. Navigate to “Model Ayarları” tab
2. Form with 4 fields: AI enabled (switch), model (cascader: Provider → Model, with tier tags and recommended stars), max tokens (select: 1024/2048/4096/8192), temperature (select: 0.1/0.3/0.5/0.7/0.9)
3. Click “Ayarları Kaydet”
4. POST /api/ai/config → saves to ai_config.json
5. POST /api/ai/reset → destroys current agent, reinitializes with new config on next query
6. Toast: “Ayarlar kaydedildi - AI yeniden başlatıldı”

Delete API Key:

1. Click “Sil” button on a provider card
2. Confirmation modal
3. DELETE /api/ai/api-keys/{provider}
4. Backend removes key from .env file and os.environ
5. Toast: “API anahtarı silindi” → card reverts to unconfigured state

Test API Key:

1. Click “Test Et” button on a configured provider card
2. POST /api/ai/api-keys/test/{provider}
3. Backend tests: Gemini via client instantiation, OpenAI via GET https://api.openai.com/v1/models, Anthropic via GET https://api.anthropic.com/v1/models
4. Success toast or error toast with details

6.3.5 AI Provider Configuration

Key Storage Architecture

API keys are stored in a .env file inside the solen_ai_service directory (separate from the main backend). They are never stored in the database. On save, the key is also set in os.environ for immediate use without restart. Keys are never returned in API responses — only masked previews (first 8 + “...” + last 4 characters).

Configuration Storage

Model settings (enabled, model_name, max_tokens, temperature) are stored in ai_config.json alongside the .env file. Defaults: enabled=true, model=gemini-3-flash, max_tokens=4096, temperature=0.7.

6.3.6 The AI Agent — Singleton Architecture

The AI agent (SolenAIAgent) is a singleton that persists across requests. It’s initialized on the first AI query and reused until explicitly reset.

The agent is reset (destroyed and recreated) when: API keys are saved/deleted, config is updated via the settings page, or POST /api/ai/reset is called. This ensures the agent always uses the latest configuration.

Chat Request Flow

1. User sends query via POST /api/ai/chat with { query, conversation_history, user_type }
2. Backend checks ai_config.json — if enabled: false, returns “AI servisi şu an devre dışı”
3. Gets or creates agent singleton, extracts user info from JWT
4. Calls agent.process_query(query, history, user_type, ip, username, user_id)
5. Agent internally: preprocesses query, selects tool, calls internal API, generates response, writes audit log
6. Backend sanitizes response (hides raw API errors), returns { success, response, tool_used, timing_ms }

6.3.7 Audit Logging — Forensic-Grade Tracking

Every AI interaction writes a row to ai_audit_logs with 47 columns of context. The audit log answers 7 questions about every query:

1. Who? — user_id, username, user_type, session info, IP, device, browser, OS
2. What? — original query, language, type (search/question/command), category (order/material/production), detected entities
3. How? — AI model, reasoning, confidence score, selected tool, tool parameters, alternative tools considered
4. Where? — API endpoint called, method, response status, response data, response size
5. Result? — success/fail, error type and message, final response text, response type
6. Performance? — total ms, AI processing ms, API call ms, response generation ms
7. Security? — injection flags, rate limit status, blocked flag and reason

6.3.8 Frontend Architecture

Single file: src/pages/Admin/AISettings/index.tsx (1,177 lines). Route: /admin/ai-settings.

4-Tab Layout

6.3.9 Permission Model

AI Settings does not have granular button-level permissions in the manifest. Access is controlled at the module level via canAdmin — any user with access to the admin module can view AI Settings. Backend endpoints have no explicit permission checks beyond JWT authentication.

This is a deliberate design choice: AI configuration is considered an admin-wide capability, not a per-button permission. In practice, only super admins access the admin module.

6.3.10 How AI Settings Connects to the Rest of the System

6.4 Kullanıcı Yönetimi (User Management)

6.4.1 Purpose and Business Context

User Management is the identity and authorization backbone of the entire ERP. Every other module — Hammadde, Teknik, Sipariş, Üretim, Stok, Lab, Admin — depends on this submodule to answer two questions: “Who is this person?” (authentication) and “What are they allowed to do?” (authorization). It is the most complex submodule in the system because it implements a hybrid permission model: legacy role-based access layered with a granular page+button permission system that controls visibility down to individual UI buttons across 8 modules, 26+ pages, and 200+ actions.

The factory has three core user archetypes: Super Admin (full system control, desktop), Lab User (quality testing, desktop), and Operator (machine operation, mobile kiosk). Beyond these, the system supports unlimited custom user types created on-the-fly, each with hand-crafted permissions.

6.4.2 Database Schema — 6 Tables, Joined-Table Inheritance

users (17 columns) — The Core Identity Table

Joined-Table Inheritance — Extension Tables

Each user type has a dedicated extension table linked via user_id FK → users.id (unique, one-to-one). These store type-specific metadata:

SQLAlchemy backrefs provide navigation: user.super_admin_profile, user.lab_user_profile, user.operator_profile.

user_sessions (11 columns)

user_roles (7 columns)

Reusable permission templates (role definitions). Each role stores a full permission JSON that can be quickly applied to users.

user_activity_logs (11 columns)

Audit trail for every administrative action on users. username is denormalized for fast reads.

6.4.3 Authentication System — JWT Tokens and Sessions

Token Architecture

The 6-month token is triggered by a hardcoded check: if user.username == 'operator'. This is deliberate — the shared operator account is used on wall-mounted phones that should stay logged in for months.

Password System

Login Flow End-to-End

1. User submits username + password to POST /auth/login
2. Backend queries user by username or email (case-insensitive)
3. Checks is_active == True and status != "suspended"
4. Verifies password with bcrypt
5. Updates last_login timestamp
6. Builds JWT payload with user_id, username, user_type, permissions
7. If operator account: sets 6-month expiry; otherwise 12-hour expiry
8. Creates UserSession row (session_token, refresh_token, device info, IP, expiry)
9. Returns { access_token, refresh_token, expires_in, user }
10. Frontend stores tokens and user in localStorage (keys: solen_auth_token, solen_refresh_token, solen_current_user)
11. Operators redirect to /production, others to /welcome

Kiosk Auto-Login

The Login page detects factory kiosk devices in two ways:

1. User-Agent detection: checks for “FullyKiosk” in the browser user-agent string (Fully Kiosk Browser is the app running on factory phones)
2. Secret URL token: checks for ?kiosk=SOLEN_FACTORY_2024_KIOSK_SECRET in the URL

If either matches, the page automatically logs in as operator / op123 and redirects to /production — no human interaction needed.

Token Refresh and Logout

1. Refresh: POST /auth/refresh with refresh token → validates, generates new access token, does not create new session
2. Logout: POST /auth/logout with access token → sets session status = "terminated" and logout_time → frontend clears localStorage

6.4.4 The Permission System — The Most Complex Part

The authorization system is a 5-layer architecture that controls access from route-level down to individual button visibility:

Layer 1: The Permission Manifest (permissionManifest.ts, 565 lines)

A static, centralized definition of every permissionable action in the entire ERP. Structured as Module → Page → Button hierarchy:

Total: 8 modules, 26+ pages, 200+ buttons.

Each button has metadata:

interface ButtonPermission {
  id: string;       // e.g. "hard_delete_material"
  label: string;    // e.g. "Kalıcı Silme"
  description: string; // e.g. "Malzemeyi veritabanından tamamen siler"
  critical?: boolean; // true = highlighted in red in permission editor
}

The manifest also exports helper functions: createEmptyPermissions() (all false), createFullPermissions() (all true), getAllPages(), getAllButtons().

Layer 2: Button Registry (buttonRegistry.ts, 130 lines)

A dynamic complement to the static manifest. Components can register their buttons at runtime via registerPageButtons(). The buildCompleteManifest() function merges static manifest pages with dynamic registry buttons. This allows new pages to self-register permissions without modifying the central manifest file.

Layer 3: Access Control — Route Guards (access.ts, 93 lines)

Runs on every route change. Parses the current user’s permissions JSON and returns boolean flags consumed by routes.ts:

return {
  canAdmin: canAccessModule('admin'),     // guards /admin/* routes
  canLab: canAccessModule('lab'),         // guards /lab/* routes
  canProduction: canAccessModule('production'),
  canHammadde: canAccessModule('hammadde'),
  canTeknik: canAccessModule('teknik'),
  canSiparis: canAccessModule('siparis'),
  canStok: canAccessModule('stok'),
  canDashboard: canAccessModule('dashboard'),
  // ... plus sub-page guards
};

canAccessModule(prefix) returns true if any page under that module has access: true. Routes use these as guards: access: 'canAdmin' in route config.

Layer 4: Permission Utilities — Component-Level (permissions.ts, 145 lines)

Provides fine-grained checks for individual components:

• canAccessModule(module) — is module enabled?
• canPerformAction(module, action) — is specific action allowed?
• hasSpecialPermission(permission) — e.g. hard_delete

Also exports React wrapper components:

• <PermissionButton module="hammadde" action="delete"> — shows/hides button based on permission
• <PermissionGuard module="admin" action="manage"> — wraps any component with permission check, shows fallback if denied

Layer 5: Backend Enforcement (permission_checker.py, 200 lines)

The server-side mirror. Even if a user bypasses the frontend, the backend enforces permissions:

Super admin bypass: Every permission function checks user.user_type == "super_admin" first and returns True immediately.

The Permission JSON Structure

Stored as a JSON string in the users.permissions column. This is the contract between frontend and backend:

{
  "pages": {
    "hammadde.hammadde_girisi": {
      "access": true,
      "buttons": {
        "add_copper": true,
        "add_tin": false,
        "submit_form": true,
        "print_qr": true
      }
    },
    "production.planning": {
      "access": false,
      "buttons": {}
    }
  }
}

6.4.5 API Contract — 14 Endpoints (9 User Management + 5 Auth)

Authentication Endpoints (5)

User Management Endpoints (9)

6.4.6 CRUD Flow

Create (New User):

1. Click “Yeni Kullanıcı” button → modal opens with 3 tabs
2. Tab 1 – Temel Bilgiler: fill username (required, alphanumeric + underscore), email (validated), full name, password (optional — auto-generated if empty), user type (select or create custom type inline), status, force password change checkbox
3. Tab 2 – Yetkiler: the permission editor — 4 quick templates at top (“Tüm Yetkiler”, “Hiçbiri”, “Operatör Varsayılan”, “Lab User Varsayılan”), then scrollable module list. Each module shows pages, each page has: access switch, “Tümü”/“Hiçbiri” quick toggles, individual button checkboxes. Critical buttons highlighted in red. Enabling a button auto-enables page access. Disabling page access disables all its buttons.
4. Tab 3 – Önizleme: read-only summary showing accessible modules → pages → enabled buttons with color-coded tags
5. Click “Oluştur” → POST /user-management/users/create with { username, email, full_name, user_type, status, permissions, force_password_change, return_password: true }
6. Backend validates uniqueness (username, email), hashes password with bcrypt, stores user + permissions JSON, logs activity
7. If password was auto-generated: modal shows the generated password with a warning “Bu şifreyi not edin, tekrar gösterilmeyecektir” (Note this password, it won’t be shown again)

Read (User List):

1. Navigate to /admin/user-management → ProTable loads via GET /user-management/users/list
2. 7 columns: ID (fixed left), Kullanıcı (username + full_name), Email, Tip (colored tag), Durum (colored tag), Son Giriş (UTC → Istanbul), İşlemler (fixed right)
3. Client-side search filters across username, email, full_name, user_type, and status simultaneously
4. Pagination: 10/20/50/100 per page
5. ProTable density and column settings controls

Update (Edit User):

1. Click edit icon (EditOutlined) on user row → same 3-tab modal opens, pre-filled with user data
2. Existing permissions loaded and parsed (handles string JSON → object conversion)
3. Password field is hidden in edit mode (use Reset Password for that)
4. Modify any field or permission → click “Güncelle”
5. PUT /user-management/users/{id} with changed fields + full permissions object
6. Backend validates, updates, logs activity

Delete (Permanent):

1. Click delete icon (DeleteOutlined, danger) on user row
2. Confirmation modal: “Bu kullanıcıyı silmek istediğinizden emin misiniz?”
3. DELETE /user-management/users/{id}
4. Backend blocks self-deletion (400 error). Hard deletes user record. Logs activity.

Suspend / Activate:

1. Click stop icon (StopOutlined) on user row
2. POST /user-management/users/{id}/suspend
3. Toggles status between active and suspended. Suspended users cannot log in.

Reset Password:

1. Click key icon (KeyOutlined) on user row
2. POST /user-management/users/{id}/reset-password
3. Backend generates cryptographically secure 12-character password, hashes with bcrypt, sets force_password_change = True
4. Modal shows new password once with warning. Admin must communicate it to user out-of-band.

6.4.7 User Types and Their Differences

Custom types (e.g. teknik_user, bakim_user, data) can be created directly in the User Management modal — an input field at the bottom of the user type dropdown allows typing a new type name. The user_type field is a free String(50), not an enum, enabling this flexibility.

6.4.8 Frontend Architecture

Single file: src/pages/Admin/UserManagement/index.tsx (960 lines). Route: /admin/user-management.

ProTable (7 columns)

The Permission Editor (Tab 2 of Modal)

The most complex UI component in the entire ERP. For each of the 8 modules:

1. Module header: module name with icon
2. Page cards: each page as a Card component with:
   • Header: Switch for page access + page label + tag showing “X/Y” enabled buttons count
   • Quick actions: “Tümü” (enable all) / “Hiçbiri” (disable all) text buttons
   • Button grid: Row/Col layout of Checkbox components for each button
   • Critical buttons: highlighted with red text and distinct styling
3. Smart toggling: enabling any button auto-enables its page access. Disabling page access cascades to disable all buttons.

Quick Templates

Preview Tab (Tab 3)

Read-only summary using Card components. Shows only accessible modules/pages. Each page lists its enabled buttons as Tags (critical ones in red). Provides a quick visual confirmation before saving.

6.4.9 Activity Logging — Admin Audit Trail

Every user management action is logged to user_activity_logs via the log_activity() helper function:

Logs are queryable via GET /user-management/activity-logs with filters for user_id, module, action, and limit (default 200). Only super admins can access this endpoint.

6.4.10 Permission Model

User Management requires the highest privilege level in the system:

In the permission manifest, User Management has 9 registered buttons: access_page, view_users, create_user, edit_user, manage_permissions, suspend_user, reset_password, delete_user, view_activity_logs.

Backend enforces role-based access: every endpoint except /user-management/operators checks current_user.user_type != "super_admin" and returns 403 if it fails.

6.4.11 How User Management Connects to the Rest of the System