EpistineFiles/epistine-webserver/README.md

EpistineFiles Webserver Migration

This project represents the migration from Streamlit to a modern FastAPI + React architecture for the EpistineFiles management system.

Architecture

Technology Stack

Backend

• FastAPI: Modern, fast (high-performance) web framework for building APIs
• PostgreSQL: Robust relational database
• Redis: Caching and session management
• SQLAlchemy: ORM for database operations
• Pydantic: Data validation and settings management

Frontend

• React 18: Modern JavaScript library for building user interfaces
• React Router: Client-side routing
• React Bootstrap: UI component library
• Axios: HTTP client for API calls
• WebSocket: Real-time communication

Infrastructure

• Docker: Containerization
• Docker Compose: Multi-container orchestration
• Nginx: Reverse proxy and load balancer

Project Structure

epistine-webserver/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI application entry point
│   │   ├── models/             # SQLAlchemy models
│   │   ├── routers/            # API route handlers
│   │   ├── middleware/         # Custom middleware
│   │   ├── database/           # Database configuration
│   │   ├── schemas.py          # Pydantic schemas
│   │   └── __init__.py
│   ├── tests/                 # Test files
│   └── requirements.txt       # Python dependencies
├── frontend/
│   ├── src/
│   │   ├── components/        # Reusable React components
│   │   ├── pages/             # Page components
│   │   ├── services/          # API service functions
│   │   ├── utils/             # Utility functions
│   │   ├── hooks/             # Custom React hooks
│   │   ├── App.js             # Main application component
│   │   └── index.js           # Application entry point
│   ├── public/               # Static assets
│   └── package.json          # Node.js dependencies
├── nginx/                   # Nginx configuration
├── docker/                  # Docker configuration
├── docker-compose.yml       # Multi-container orchestration
└── README.md               # This file

Getting Started

Prerequisites

• Docker and Docker Compose

Running the Application

The webserver components are available as pre‑built Docker images from the Gitea container registry. To start the full stack:

1. Clone the repository
2. Navigate to the project directory
3. Start the services using Docker Compose:

   docker-compose up -d
   

4. The application will be available at:
   • Frontend: http://localhost:3000
   • Backend API: http://localhost:8000
   • Nginx: http://localhost

Note

: The Docker Compose configuration builds images locally. For production use, pre‑built images are available from gitea.kareemhorstink.me.

API Endpoints

Authentication

• POST /api/auth/login - User login
• POST /api/auth/register - User registration

Agents

• GET /api/agents - List all agents
• POST /api/agents - Create new agent
• GET /api/agents/{id} - Get specific agent
• PUT /api/agents/{id} - Update agent
• DELETE /api/agents/{id} - Delete agent

Tasks

• GET /api/tasks - List all tasks
• POST /api/tasks - Create new task
• GET /api/tasks/{id} - Get specific task
• PUT /api/tasks/{id} - Update task
• DELETE /api/tasks/{id} - Delete task

Logs

• GET /api/logs - List all logs
• POST /api/logs - Create new log

Settings

• GET /api/settings - List all settings
• POST /api/settings - Update setting

WebSocket Events

Client → Server

• subscribe:agents - Subscribe to agent updates
• subscribe:tasks - Subscribe to task updates

Server → Client

• agents:update - Agent status update
• tasks:update - Task status update
• system:alert - System alert

Database Schema

The application uses PostgreSQL with the following main tables:

agents

• id (Primary Key)
• name (String)
• status (String)
• capabilities (JSON)
• created_at (DateTime)
• updated_at (DateTime)

tasks

• id (Primary Key)
• agent_id (Foreign Key)
• status (String)
• result (JSON)
• created_at (DateTime)
• completed_at (DateTime)

logs

• id (Primary Key)
• level (String)
• message (Text)
• timestamp (DateTime)

settings

• id (Primary Key)
• key (String)
• value (Text)
• description (Text)
• created_at (DateTime)
• updated_at (DateTime)

Environment Variables

Backend

• DATABASE_URL - PostgreSQL connection string
• REDIS_URL - Redis connection string
• SECRET_KEY - JWT secret key
• API_KEY - API key for external services

Frontend

• REACT_APP_API_URL - Backend API URL
• REACT_APP_WS_URL - WebSocket URL

Security

Authentication

• JWT-based authentication
• Password hashing with bcrypt
• API key authentication for external services

Authorization

• Role-based access control (RBAC)
• Permission-based resource access
• Rate limiting

Data Protection

• Input validation and sanitization
• SQL injection prevention
• XSS protection
• CSRF protection

Support

For support and questions:

• Create an issue in the repository
• Check the documentation in the /docs folder
• Contact the development team

---

Note: This is a migration project. The original Streamlit application has been completely replaced with this modern FastAPI + React architecture for improved performance, scalability, and user experience.