☁️ Clouds ☁️

❓ What is it?

Clouds is a multi-purpose web environment, runnable locally on the user machine or on a server. The provided environment is accessible through any modern web browser, allowing its core functionality to be available on any number of devices, including but not limited to: PCs, Smartphones, Smart TVs, etc.

Here's a list of some things you can do with Clouds:

• Stream content from your computer or laptop to your TV;
• Manage local/remote media server files with an intuitive interface.
• Transfer files between your Phone and your computer with ease;
• View documents like PDFs on any capable browser directly in the UI;
• Invoke shell and sysadmin commands remotely from any of your devices;
• And more to come!

Clouds uses the concept of apps to perform many functionalities on its environment. Apps are separate from the core system, and can be developed independently from the rest of the project, allowing flexibility and most importantly extensibility.

📁 Structure

This project consists of three separate entities: The API, the Client core and the included Apps.

• API: Encompasses all the functionalities pertaining to the services provided in the server. Targets the server device. It uses Node.js with Express to provide a simple but powerful routing system consumed by the web client.

• Client: Encompasses all subsystems targeting the client device, that is, the web browser accessing the web interface. Uses standard modern TypeScript, compiled through Webpack and Babel for better performance and support of older devices. Consumes the API through the browser.

• Apps: Built-in apps written in TypeScript to provide support to basic functionalities in the environment. These are also compiled through Webpack and Babel to provide performance and support of older devices. These apps are compiled against the client core platform.

Directory	Purpose
api/src/	Core classes written in TypeScript used by the Node.js server. These must be compiled.
api/runtime/	Compiled core classes from source. These are generated by the tsc compiler.
api/pages/	Web pages loaded by the client when initializing the system.
client/src/	TypeScript source code for the core client modules. These are compiled into final static resources.
client/public/	Static general resources, accessible directly by the client web browser.
apps/	Contains a folder for every built-in app available on the system. An app folder contains a manifest, modules and resources used by the app.
config/	Configuration used by the server.
docs/	Files associated with the repo documentation.
usr/	Contains a folder for each user in the web system. Provides a dedicated space that can be used by the client user.

📦 Building

1) Preparation

You must install all NPM dependencies. Some dependencies are meant to be used at runtime and others are build tools. Here's the main dependencies of the project, the ones listed in italics are dev dependencies:

Dependency	API	Client
Express	Yes	No
EJS	Yes	No
TypeScript	Yes	No
Babel	No	Yes
Webpack	No	Yes

All of these dependencies can be installed with: > npm install on the root of a fresh clone of the repository.

2) Building API

The API is written in TypeScript, and must be compiled first before being executed as a server. To compile the API, run > npm run build-api-dist. This script invokes tsc to perform the type-checking and compilation of all TypeScript files in /api/src/ and put them in /api/runtime/.

3) Building Client Core

The core modules used by the Client system are also written in TypeScript and must be compiled through Webpack in order to be available in the /client/public/ directory. You can invoke an npm script to do this compilation. Simply run > npm run build-client-prod in the root of a project.

4) Building Built-in Apps

The built-in apps in /apps/ are written in TS and must also be compiled with Webpack and Babel. Run > npm run build-apps-prod to perform compilation.

5) Configuration

You are done! You can configure the behavior of the server through the profiles stored in config/profiles/. The default profile is already well configured, but you might want to change a few settings.

Here's a list of all NPM scripts that can be used through > npm run <script>

Script	Purpose
build-api-dist	Compiles all the TypeScript API files in /api/src/ to /api/runtime/
build-client-prod	Compiles and Bundles the Core client modules in /client/src/ to /client/res/js/ in production mode.
build-client-dev	Compiles and Bundles the Core client modules in /client/src/ to /client/res/js/ in development mode.
build-client-types	Runs TypeScript compiler type checking on Client code and emits declaration files on /client/types/ folder.
check-client-stats	Compiles and Bundles the Core client modules in /client/src/ to /client/res/js/ in stats analysis mode.
build-apps-prod	Compiles apps on /apps/ in production mode.
build-apps-dev	Compiles apps on /apps/ in development mode.
check-apps-type	Check types of all apps in /apps/.

▶️ Running

After building the project, running it is as easy as double-clicking the run script that matches your OS on the root of the project. You can also invoke node directly with the same effect as the script. On a fresh terminal in the root, run the command > node ..

This will instantiate a new server on the current machine and automatically start listening for new client connections. The terminal will stay open and log some of the user activities. Which activities are logged can be configured in the forementioned profiles stored in the config/profiles directory.

📜 API Routes

Route	Maps to	Purpose
/	/api/pages/entry	Initial page.
/auth/	-	Authentication services: login, logout, test
/page/	/api/pages/	Fetching of core HTML pages, mainly login and desktop page.
/res/	/client/public/	Static resource access. All logged in users can access any content in this directory.
/@sys/	/client/res/js/	Static core JS modules. Compiled through Webpack from /client/src/
/app/<name>	/client/apps/<name>	Fetch static app resources.
/fsv/	(User filesystem)	Read/write file system access at the current path.
/shell/	-	Manage user remote shells.
/stat	-	Obtains system-wide status information.