# Architecture

## Purpose

This document describes the target MVP architecture for a server management web panel with future Telegram bot integration.

## Goals

- provide a safe web interface for viewing server state and controlling approved services;
- share business logic between the web panel and Telegram bot;
- keep the first version simple, auditable, and easy to deploy;
- avoid direct arbitrary command execution from UI or bot.

## Non-Goals for MVP

- multi-tenant SaaS architecture;
- advanced live terminal access;
- arbitrary shell command execution;
- full observability platform replacement;
- high-availability clustered deployment.

## High-Level Design

The system consists of four main parts:

- `frontend`: web UI for operators and administrators;
- `backend`: REST API, authentication, authorization, validation, audit, and orchestration;
- `worker`: background execution for control actions and notifications;
- `bot`: Telegram integration that uses the same backend logic and permission model.

## Logical Flow

1. The user signs in to the web panel.
2. The frontend calls backend API endpoints.
3. The backend authenticates the user and checks permissions.
4. Read-only data is returned immediately.
5. Control operations are stored as actions and sent to a worker.
6. The worker executes an approved operation against the target server.
7. The result is stored in audit logs and optionally sent to Telegram.

## Component Diagram

```text
[Browser UI]
     |
     v
[Frontend React App]
     |
     v
[FastAPI Backend] ---> [PostgreSQL]
     |                      |
     |                      v
     |                 [Audit / Users / Servers / Actions]
     |
     +----> [Redis / Queue] ----> [Worker]
     |                               |
     |                               v
     |                         [SSH / systemd / Docker integration]
     |
     +----> [Telegram Bot]
                 |
                 v
            [Telegram Users]
```

## Recommended Runtime Layout

## Frontend

- React + Vite single-page application
- uses backend API only
- no direct server access

## Backend

- FastAPI application
- owns authentication and authorization
- validates all incoming requests
- exposes REST API for UI and bot integration

## Worker

- executes asynchronous jobs:
  - service start;
  - service stop;
  - service restart;
  - log retrieval if needed asynchronously later;
  - Telegram notification delivery.

## Bot

- separate Python process
- linked to backend or shared backend modules
- should not bypass backend permissions or audit logging

## Data Model Overview

## Core Entities

- `User`
  - id
  - username
  - password hash
  - role
  - is_active
  - created_at

- `Server`
  - id
  - name
  - host
  - port
  - ssh_username
  - connection_type
  - environment
  - is_active
  - created_at

- `ManagedService`
  - id
  - server_id
  - service_name
  - service_type
  - control_enabled
  - log_source

- `Action`
  - id
  - server_id
  - service_id or service_name
  - action_type
  - requested_by
  - source
  - status
  - requested_at
  - completed_at

- `AuditLog`
  - id
  - actor_id
  - actor_source
  - target_type
  - target_id
  - action
  - result
  - metadata
  - created_at

- `TelegramLink`
  - id
  - user_id
  - telegram_user_id
  - chat_id
  - linked_at

## Access Model

Recommended roles:

- `admin`
  - manages users, servers, Telegram linking, and service control
- `operator`
  - views servers, metrics, logs, and can run allowed service actions
- `viewer`
  - read-only access to dashboard, metrics, and logs

## Security Principles

- never expose direct shell execution to frontend users;
- only allow actions from a predefined whitelist;
- store secrets in environment variables;
- hash passwords securely;
- protect sensitive endpoints with role checks;
- audit all control operations;
- validate all Telegram-triggered actions against linked user roles.

## Server Control Options

There are three possible control strategies.

## Option A: SSH-Based Control

The backend or worker connects to servers over SSH and runs predefined commands.

Pros:

- simple to start;
- no custom agent required;
- works well for small infrastructure.

Cons:

- secrets management is more sensitive;
- command execution must be tightly constrained;
- harder to scale cleanly later.

Best fit for MVP:

- yes, if the number of servers is small and commands are tightly whitelisted.

## Option B: Local Agent on Target Server

A small agent runs on each managed server and exposes limited capabilities.

Pros:

- cleaner long-term security model;
- easier to standardize metrics and service control;
- can reduce SSH complexity.

Cons:

- more implementation work;
- extra deployment surface.

Best fit for MVP:

- probably not required unless you already know SSH is unsuitable.

## Option C: Docker/API-Native Control

For container-based infrastructure, the system talks to Docker or orchestrator APIs directly.

Pros:

- structured operations;
- less shell parsing.

Cons:

- only covers Docker-managed workloads;
- still needs role and scope restrictions.

Best fit for MVP:

- good if most managed services are containers.

## Recommended MVP Choice

Start with:

- SSH for Linux host access;
- predefined `systemd` commands for host services;
- predefined Docker commands or API wrappers for containerized services.

For the current implementation slice:

- reachability is checked with a TCP connection to the configured host and port;
- metrics are collected over SSH using predefined read-only commands;
- SSH metrics require a configured `ssh_username`;
- managed services are stored in the application database;
- control actions use predefined `systemd` or Docker commands only;
- action and audit records are written for control operations;
- logs are read over SSH from `journalctl`, `docker logs`, or `file:/absolute/path`.

Do not support free-form command execution in the first version.

## Action Execution Model

All write operations should follow this pattern:

1. API receives a control request.
2. API validates user role and target service.
3. API creates an `Action` record with status `pending`.
4. API pushes a job to the queue.
5. Worker executes the action.
6. Worker stores result and updates action status.
7. Worker writes an audit log record.
8. Worker sends Telegram notification when configured.

This keeps UI requests fast and preserves traceability.

Current implementation note:

- the data model and audit flow are already in place;
- the API creates `pending` action rows and the worker claims them from the database;
- this keeps the first worker implementation small without introducing a second queue format yet.

## Metrics Strategy

For MVP, collect:

- CPU usage
- memory usage
- disk usage
- uptime
- load average
- service state

Metrics may be fetched on demand rather than via a full monitoring pipeline.

## Logging Strategy

For MVP, support:

- recent logs only;
- line-limited responses;
- per-service log source configuration;
- no live streaming terminal session.

Possible sources:

- `journalctl` for `systemd` services;
- `docker logs --tail N` for containers;
- file-based logs where explicitly configured as `file:/absolute/path`.

## Telegram Integration Model

The bot should support two classes of behavior:

- notifications
  - service restart success or failure
  - server health alerts later
- commands
  - `/start`
  - `/status`
  - `/services`
  - `/restart` for approved users only

The bot must:

- link Telegram identity to an internal user;
- enforce the same permissions as the web UI;
- record all bot-originated actions in audit logs.

## Deployment Model

For the MVP, a single-host deployment is acceptable:

- reverse proxy: Nginx
- frontend container
- backend container
- worker container
- PostgreSQL container
- Redis container
- bot container

This is sufficient for internal or early-stage use.

## Failure and Safety Considerations

- if backend is unavailable, UI and bot commands should fail closed;
- if worker is unavailable, actions should remain pending and visible;
- if Telegram is unavailable, action execution should still complete;
- if server access fails, the system should capture error details in the action result and audit log.

## Recommended Documentation Set

- `docs/architecture.md`
- `docs/api.md`
- `docs/roadmap.md`
- `docs/checklist.md`
- `docs/deployment.md`
- `docs/rollback.md`
- `docs/telegram.md`

## Open Questions

Before implementation, confirm:

- how many servers are in scope for MVP;
- whether all targets are Linux;
- whether services are mostly `systemd`, Docker, or mixed;
- whether Telegram should allow control commands in MVP or only notifications;
- whether one environment or multiple environments are needed from day one.