# Functional Specification
## 0. Table of Contents
1. [Introduction](#1-Introduction)
    1. [Overview](#11-Overview)
    2. [Business Context](#12-Business-Context)
    3. [Glossary](#13-Glossary)
        1. [Panoptes](#131-Panoptes)
2. [General Description](#2-General-Description)
    1. [Product/System Functions](#21-ProductSystem-Functions)
    2. [User Characteristics and Objectives](#22-User-Characteristics-and-Objectives)
    3. [Operational Scenarios](#23-Operational-Scenarios)
        1. [Module Installation](#231-Module-Installation)
        2. [Module Control](#232-Module-Control)
        3. [Function Permission Denied](#233-Function-Permission-Denied)
        4. [User Login and Verification](#234-User-Login-and-Verification)
    4. [Constraints](#24-Constraints)
        1. [Security Constraints](#241-Security-Constraints)
        2. [Server Constraints](#242-Server-Constraints)
        3. [Timing Constraints](#243-Timing-Constraints)
3. [Functional Requirements](#3-Functional-Requirements)
    1. [User Authentication](#31-User-Authentication)
        1. [Description](#311-Description)
        2. [Criticality](#312-Criticality)
        3. [Technical Issues](#313-Technical-Issues)
        4. [Dependencies](#314-Dependencies)
    2. [Hierarchy Management](#32-Hierarchy-Management)
        1. [Description](#321-Description)
        2. [Criticality](#322-Criticality)
        3. [Technical Issues](#323-Technical-Issues)
        4. [Dependencies](#324-Dependencies)
    3. [Module Installation](#33-Module-Installation)
        1. [Description](#331-Description)
        2. [Criticality](#332-Criticality)
        3. [Technical Issues](#333-Technical-Issues)
        4. [Dependencies](#334-Dependencies)
    4. [Module Control](#34-Module-Control)
        1. [Description](#341-Description)
        2. [Criticality](#342-Criticality)
        3. [Technical Issues](#343-Technical-Issues)
        4. [Dependencies](#344-Dependencies)
    5. [Container Orchestration](#35-Container-Orchestration)
        1. [Description](#351-Description)
        2. [Criticality](#352-Criticality)
        3. [Technical Issues](#353-Technical-Issues)
        4. [Dependencies](#354-Dependencies)
    6. [Statistics Display](#36-Statistics-Display)
        1. [Description](#361-Description)
        2. [Criticality](#362-Criticality)
        3. [Technical Issues](#363-Technical-Issues)
        4. [Dependencies](#364-Dependencies)
    7. [Security](#37-Security)
        1. [Description](#371-Description)
        2. [Criticality](#372-Criticality)
        3. [Technical Issues](#373-Technical-Issues)
        4. [Dependencies](#374-Dependencies)
4. [System Architecture](#4-System-Architecture)
    1. [Diagram](#41-Diagram)
    2. [Go Server](#42-Go-Server)
    3. [Blazor Backend](#43-Blazor-Backend)
    4. [Blazor Frontend](#44-Blazor-Frontend)
    5. [Postgresql](#45-Postgresql)
    6. [Docker](#46-Docker)
5. [High Level Design](#5-High-Level-Design)
    1. [User Installs Module](#51-User-Installs-Module)
    2. [User Creates/Updates Role Permissions](#52-User-CreatesUpdates-Role-Permissions)
    3. [User Manages Module](#53-User-Manages-Module)
6. [Preliminary Schedule](#6-Preliminary-Schedule)

## 1. Introduction
### 1.1 Overview
Panoptes is a web application that allows users to manage servers and any services they control all in a single place. The system will alow users to create and manage modules, which will be used to gather data and control external services, as well as optionally install services associated with those modules. Panoptes will also allow users to create role hierarchies which will limit what functions of modules a given user can access.
### 1.2 Business Context
As a product, Panoptes is aimed towards any business that requires system administration, and towards Homelab administrators running their own services.

From an enterprise perspective, Panoptes will be very useful due to system adminstrartors being able to easily create or install modules for their custom services, like any monitoring tools that they set up, without having to find an interface that has everything that they want. 

They will also particularly benefit from the permissions system, which will allow them to give access to certain functions to more junior staff, while allowing senior staff access to more privileged functions.

Meanwhile, homelab administrators will benefit from the ability to create or install modules to monitor and control services they have set up themselves in a way that suits their niche use case.

### 1.3 Glossary
#### 1.3.1 Panoptes
Panoptes is the name of the project - a modular web interface for managing servers and services.

Module - A user-created package that provides functionality for use cases not covered by the base software.


## 2. General Description
### 2.1 Product/System Functions
Using Panoptes you will be able to:

- Monitor and control services.
- Install user-created modules for control of custom or niche tools/services.
- Curate a list of tools and services to monitor on the same user interface.
- Implement user permissions to restrict or allow access to certain functions withen modules.

### 2.2 User Characteristics and Objectives
<!--(Identify the users: admin, teachers, students)
whart are their demographics (age range) and what is their level of technical capabilities. Digital literacy.

What would each person like to do? What is the benefit of the software of the users-->
The primary user of Panoptes is an administrator of a server or fleet of servers. As Panoptes is primarily aimed towards people in technical professions, it is a reasonable assumption that users will have some degree of technical knowledge.
### 2.3 Operational Scenarios


#### 2.3.1 Module Installation

The user wants to install a new module to monitor a web server they have set up. First the user will select the 'add module' button,from here they will see a list of approved user-created modules. 

As well as that, the user can paste a URL to a repository containing the source code for a module they've eitjer wrote or found that suits their specific use case. After pasting in the required URL the user can click 'install' and the installation process begins.

#### 2.3.2 Module Control

The user would like to configure what port their apache web server is running on. From our main menu they can select the module controlling their apache server.

From here they will see a summarised version of any important information regarding this server i.e port number, server load etc

After selecting the module they will see a list of functions and configurable settings. The user selects the setting for 'port number' and changes the number. They can then save and restart the server and observe it operating on a new port.

#### 2.3.3 Function Permission Denied

The user is a junior adminstrator in an organisation. They wish to configure a setting within a module to fix an issue however they do not have access to it as their user account has been assigned the 'junior' role within the organisation.

The user must ask someone holding the 'senior' role or higher to configure the setting for them as only they have access to that specific function of the module.

#### 2.3.4 User Login and Verification

User opens Panoptes and and is prompted to either log in or create an account. To log in, the user simply will enter their username and password which will be checked against our database and authorised using the OAuth 2.0 framework.

Similarly, if the user has not registered an account they will be prompted to enter a username and password. Once they have done this the system will check if the username and password are valid, create the account and add it to our database.

### 2.4 Constraints
<!--Lists general constraints placed upon the design team, including speed requirements, industry protocols, hardware platforms, and so forth.-->
#### 2.4.1 Security Constraints
This web application will need to be developed in a way that prevents users and malicious actors from accessing data or functions that they should not be able to access.

#### 2.4.2 Server Constraints
The server hosting Panoptes will need to support the same architectures that we have access to, due to the fact Docker requires systems to have the same archtecture. It is also important that the server is able to communicate using websockets, as they will be instrumental to the functioning of the web application.

#### 2.4.3 Timing Constraints
Due to the limited amount of time available to complete this project, it will be important that we manage our time efficiently if we want to implement every feature.

## 3. Functional Requirements
<!--This section lists the functional requirements in ranked order. Functional requirements describes the possible effects of a software system, in other words, what the system must accomplish. Other kinds of requirements (such as interface requirements, performance requirements, or reliability requirements) describe how the system accomplishes its functional requirements.

As an example, each functional requirement could be specified in a format similar to the following:
Description - A full description of the requirement.
Criticality - Describes how essential this requirement is to the overall system. (how important is it)
Technical issues - Describes any design or implementation issues involved in satisfying this requirement. (browser compatibility, server load, ML errors)
Dependencies with other requirements - Describes interactions with other requirements. (does it depend on anything else)
Others as appropriate-->
### 3.1 User Authentication

#### 3.1.1 Description
Panoptes must be able to verify that a user should have access to its features. This will be achieved by implementing user accounts using the OAuth 2.0 framework for authorisation and storing account information in our database.

#### 3.1.2 Criticality
This is a critical feature as only authorised users should be able to access panoptes' functionality for security reasons.

#### 3.1.3 Technical Issues
We dont foresee any technical issues with this feature.

#### 3.1.4 Dependencies
This feature is not dependant on any others.

### 3.2 Hierarchy Management

#### 3.2.1 Description
Within an organisation, it would be a security risk to allow all members of staff access to all functionality and configurations of a server. 

To combat this we are implementing a hierarchy management system using roles. Roles will have a hierarchy and can be assigned to a user to restrict or give access to certain functionality within a given module.

#### 3.2.2 Criticality
While this solves potential security issues it is not critical for panoptes to function.

#### 3.2.3 Technical Issues
If a user has multiple roles, we need to ensure that they have cascading permissions. This is to say that they have the permissions of the highest priority role and if a permission is not defined in that role, it checks the next highest priority role.

#### 3.2.4 Dependencies
This feature is dependant on user registration/authentication as roles will need to be assigned to user account.

### 3.3 Module Installation

#### 3.3.1 Description
The core design of Panoptes revolves around the installation of custom modules. This feature involves taking code from a repository and spinning up a docker container for the module to exist in.

#### 3.3.2 Criticality
This Feature is critical for panoptes to function as without it we will have no method of monitoring and controlling our services.

#### 3.3.3 Technical Issues
We forsee issues in grabbing and running code from repositories. Security will also be a concern with community made modules.

#### 3.3.4 Dependencies
This Feature has many dependencies. First of all, our security measures must be put in place. Secondly it will depend on container orchestration so that the docker containers that contain modules can be managed by the system. Lastly only an authenticated user can install modules which requires user authetication to work.


### 3.4 Module Control

#### 3.4.1 Description
With a module installed a user should be able to monitor, control and configure said module through Panoptes' user interface.


#### 3.4.2 Criticality
This feature brings the core functionality to Panoptes and is therefore of upmost criticality.

#### 3.4.3 Technical Issues
Because modules can be so varied depending on the service it will be a complex task to ensure we can facilitate all kinds of required functionality.


#### 3.4.4 Dependencies
This feature is dependant on the ability for modules to be installed in the first place.

It also depends on our container orchestration feature so panoptes can manage the container that the module lives in.


### 3.5 Container Orchestration
#### 3.5.1 Description
Panoptes must be able to manage the containers used to run any modules installed on it. This will be done using the API provided by Docker.
#### 3.5.2 Criticality
This is a critical aspect of our application, as without it the application cannot exist.
#### 3.5.3 Technical Issues
One of the biggest technical issues will be keeping track of what containers are a part of this application and which ones are not. To help with this we will use labels to mark which containers are owned by the application.
#### 3.5.4 Dependencies
This feature will not depend on any other components of the application.

### 3.6 Statistics Display
#### 3.6.1 Description
Panoptes must have a framework that can be used to display statistics. In order to achieve this, we will build a library of components that can be easily dynamically generated with statistics embedded in them.
#### 3.6.2 Criticality
This aspect of the application is very important for user experience, as although the system will function without it, users will find it very useful for browsing the statistics generated by modules.
#### 3.6.3 Technical Issues
We do not foresee any technical issues with this feature.
#### 3.6.4 Dependencies
This feature will not depend on any other components of the application.

### 3.7 Security
#### 3.7.1 Description
As Panoptes will have a lot of access to the machine it runs on, it is important that the system is secure and cannot be used maliciously.
#### 3.7.2 Criticality
Security is the most critical aspect of the application. The security of the application must protect from data and functions being accessed by people who shouldn't have access to them.
#### 3.7.3 Technical Issues
Installing community created modules is often a bad idea, so to mitigate security flaws all modules will be installed as docker containers, with only access to the resources required by it.
Additionally, exposing the API that manages the containers is also a security risk, so to mitigate any security flaws arising from that, the application will function without the API being exposed.
#### 3.7.4 Dependencies
This feature will not depend on any other components of the application.

## 4. System Architecture

<!--This section describes a high-level overview of the anticipated system architecture showing the distribution functions across (potential) system modules. Architectural components that are reused or 3rd party should be highlighted.

list the components and write a short description.-->
#### 4.1 Diagram
![](https://plantuml.malmal200.xyz/png/oyjFILLGSafCpaxDIr5IgEPIK8XsoacioYzIW0h6OX5IqDMrKuXsprS8JYqgIosAvQhbuie3c-HMb9zNWjCeY3we84mfacwNVA2w8gXUXF4GRRxvAQKvgGh6iNWaZV196e9jIaaiIKnAB0RQ5f1VN99Ub5fSc0Eo4IY5hX6X0000)

#### 4.2 Go Server
The Go server takes requests from the Blazor frontend, and optionally from an external service, and uses those requests to interact with the Postgresql database, with Docker, and the containers it has set up.
#### 4.3 Blazor Backend
The Blazor backend will handle all data processing between the Blazor frontend and the Go server. It will also handle any rendering that takes place for the Blazor frontend.
#### 4.4 Blazor Frontend
The Blazor frontend will be what the user interacts with when using Panoptes. It will be used to display data, and also for the user to make any changes to to installed modules or  configure the monitored services.
#### 4.5 Postgresql
The Postgresql database will be used to store information such as user account details and module permissions.
#### 4.6 Docker
A Docker instance will have a series of containers managed by the Go server, which will be used to store modules and be interfaced with by the Go server.
## 5. High-Level Design
<!--Sequence diagrams 
state diagrams
Data flow diagrams 
This section should set out the high-level design of the system. It should include one or more system models showing the relationship between system components and the systems and its environment. These might be object-models, DFD, etc.-->
#### 5.1 User Installs Module
![](https://plantuml.malmal200.xyz/png/XPB1JiCm44Jl_efLxZcqIIy88L5LHJqW48WFMEobYd2yO3kWylKuiTDIDwK-M97dUNOy2ahF5j9wSRJ_tYzqi6OMP7pZT-ciM6hy2VVMbeqdeue3E9icboZVHp2HyuoyOtWc-qMso8TNGhBM97t3nW6iE7ZPoPYrKEZn5HqDXu_i_DQI-zGdv4A8i4DvCuI6AtZu80CjgquJDCPvr1hxWMBG8pU_o5sNvGW-XVU6c6VGaPpzJsOXDr5BQ1xjL9qdjPfKgwGkWdghr1Z0CumjHYf5xR5DYri2rqb9phrrMky0bIBrrwuEt8g_ZMPKW4Q1xGwDzVUFNElCDPfQD35_ele7t4UBe-6fh1XWglv40sbgm_zsflgC-WK0)

#### 5.2 User Creates/Updates Role Permissions
![image alt](https://plantuml.malmal200.xyz/png/ZT1DQiCm40NWlKunU1-ARR89fOiKacLBGWymbQR1LDQu6haXFNqLI_cfavHe8OJu7Xezr84zvFKcT3mV5meic1Mvq8HTlYlc5dzYRk7P1NAcEC7okfoZ_Zp0BAkHN3AioN-JByQFryfWm7SK6YvVMSB6atpPYp6dIiKT9a_3A3DuwSX1HxvjH1fsqAB33RNnOTWspl1spyligxlzuoJxLVnJxEoKa3ENMVaV-plkcW9ujdGkHnFU8bKczMrIPpATmRCd3FJGTx5OIXYT0JG60iEXRPLIwHinjTexFKHDpXgGNciI-UYjtQL1ag_lz9TjPW5aX-QlLZaolm00)

#### 5.3 User Manages Module
![](https://plantuml.malmal200.xyz/png/dPE_ReCm48TtFyM9dO4_MQggGwYICL6hFe1hBWJ5sDHdMhLFNyT0Y0nqg0U4xlTnT_uakB3Qm73U26_ljyC9TbepLBQstqCjsah-uxxR6QqigZAQm6IPt79n6S61J0Doh-4LpIUQA1oUCQ6bH65hhGZWMRjUPd7Dd9NSydTEw8j7JROoI1zoHcuOSq-8d_pIy0275XKqkkmaGiihPBxUv-bAdWvvvl8zsZ4cooqnN-_pZSkBCueBT5V5BPgc9hhUfgSUutZ4Nj1sHgrmVRTyTThG9v_wX4mwCjawaunCwXbLkbM2Yuz4iam4QeipLnM2qEfKLw7NMNWlTHR-m-Xnoe1BgR-m36qkZBbJMVWoY1wYJWWaEdLovlClS4dgG01ARDo_i28se7u1)

## 6. Preliminary Schedule
We have set up our project into four distinct phases.

Phase three and four contain the bulk of the work. Phase one and two involve setting ourselves up for success by laying the foundations for phase three and four.

![](https://md.malachy.ie/uploads/1e61d852bb021290e46d85c00.png)

![](https://md.malachy.ie/uploads/1e61d852bb021290e46d85c01.png)

![](https://md.malachy.ie/uploads/1e61d852bb021290e46d85c02.png)

![](https://md.malachy.ie/uploads/1e61d852bb021290e46d85c03.png)

