S²AGittarius - Smart Service Architecture Generator

Index

Introduction

• What is S²AGittarius
• Users
• The Black Box hypothesis

Components

• Client
• Server
• Compiler

Contributing

• Getting started
• Project structure

Building

• Individual components
• Entire Project

Inquiries

Copyright

Introduction

What is S²AGittarius

S²AGittarius (Smart Service Architecture Generator) is an ecosystem of services that fulfil 3 main goals:

• Develop smart service and IOT-based apps.
• Analyse data from existing (and user-created) services.
• Browse and archive existing services.

Users

There exist two kinds of users that our product tries to reach out to and whose needs we wish to satisfy:

• Non-technical users, whose main goal is taking a formal description of their goals and see it being achieved, in the most transparent and painless way.
• Technical users, who are looking for solutions to streamline their development process and that would see collaborations between users of different backgrounds as a source of enrichment and variety to the ecosystem.

The Black Box hypothesis

In the scientific and philosophical world, a Black Box is a system whose only known features are the requirements and the results, abstracting away complexity and precise implementation details. This should constitute, by no means, the refusal for the project to belong in the open source environment or to hide security flaws through obscurity. The idea behind a Black Box model refers to the expected user experience such system would like to achieve: that is, taking the user's needs and providing meaningful results, without requiring document skimming, arduous API specifications or the need for further tools to be adopted into the architecture. We wish for our product to be plug-and-play by design.

Components

Client

The S²AGittarius client is the main interface most users will interact with on a daily basis. On a philosophical level, it represents the entry point to the Black Box. The client is made up of 2 main components:

• Editor: in the Editor, users can compose new projects, by writing .sags (pronunciation) files. The editor offers basic syntax highlighting capabilities. In future, we envision the editor offering a NodeRed editing version as well as providing more advanced syntax highlighting.
• Browser: in the Browser, users can find other smart services, filter them by scope, location or scale, as well as select pre-existing or user-defined templates for their own projects.

Techstack:

• Vue
• Typescript
• Vite
• Monaco Editor

Server

The S²AGittarius client serves as a router for every other service in the ecosystem. It comprises 3 main routes which abstract communication between services:

• /auth: handle user authentication. User authentication is handled by a Supabase instance.
  • /login [username: str, password: str] → login as an existing user.
  • /signup [username: str, email: str, password: str] → register a new user.
  • /logout → terminate current session and log out.
• /data: retrieve data from one external data source. Data sources include our Supabase instance as well as other consortium partner's services.
  • /devices → find devices and services.
  • /documents → find documentations.
  • /organisations → find organisations.
  • /measures → find data gathered by other services.
  • /templates → find project templates built-in or generated by other users.
• /compile: send a .sags file to a remote SAG-Compiler instance and deploy a full-stack web app on successful compilation.
  • /build → upload a .sags file and build a compiled .ssd file (for caching purposes only).
  • /export → upload a .sags file and build a full-stack web app with a docker compose file (for local hosting purposes).
  • /deploy → upload a .sags file and deploy a full-stack web app on the specified provider.

Techstack:

• Express
• Prisma
• Supabase
• Typescript
• tRPC

Compiler

The S²AGittarius compiler is responsible for transforming source .sagc files into full-stack web apps. The compiler itself is composed of 3 layers:

• Frontend: The compiler frontend is responsible for preliminary parsing and caching of source files. Its job is to parse .sagc files into .ssd files, which serve as intermediate representation for the compiling process.
• Linker: The compiler linker is responsible for taking intermediate representation files and compile them into a full-stack web app (constituted of a FastAPI backend and a Typescript frontend [precise framework to be defined]) and a Dockerfile for deployment.
• Orchestrator: The compiler orchestrator is responsible for taking a full-stack web app and a Dockerfile and deploy it remotely.

Techstack:

• Rust
• nom
• Rocket

Contributing

Getting Started

Clone all repositories by running the following commands:

git clone --recurse-submodules https://github.com/IMC-UAS-Krems/Sagittarius

git clone https://github.com/IMC-UAS-Krems/Sagc compiler

git clone https://github.com/IMC-UAS-Krems/Sagittarius-Client client

git clone https://github.com/IMC-UAS-Krems/Sagittarius-Server server

This project makes use of git submodules, thus it is necessary to operate on the INDIVIDUAL repositories, rather than the monorepo.

• Step 1: Clone the repository

git clone <component-name>

• Step 2: Install dependencies

  • Typescript projects:
    • npm install
  • Rust projects:
    • rustup update
    • rustup default nightly
    • cargo build (or cargo run)

• Step 3: Save your changes and push them to the repository

git add .

git commit -m "commit message"

git push

• Step 4: Propagate changes to the monorepo

cd <monorepo-folder>

git submodule update --remote

• Step 5: Commit and push changes to the monorepo

git add .

git commit -m "commit message"

git push

Project Structure

The project is structured as follows:

• client contains the source code for the S²AGittarius client.
• compiler contains the source code for the S²AGittarius compiler.
• server contains the source code for the S²AGittarius server.

In order to contribute to each repository, please refer to the individual git projects. Make sure to follow the instructions in the README files.

Building

Individual Components

Individual components can be built by following the instructions in the README files of each repository.

Docker

Dockerfiles for each component are available in the respective repositories.

Build the images following these steps:

docker build -t <image-name> .

Run the images following these steps:

docker run -p <host-port>:<container-port> <image-name>

Alternatively, you may use Docker Desktop to build and run the images.

Entire Project

To build the entire project make use of the Docker compose file provided in this directory.

Firstly, expose the environment variables:

source .env

Build the images

docker-compose build

Run the images

docker-compose up

Inquiries

If you face any problem with documentation and/or development please refer to Antonino Rossi.

Copyright

© 2022 IMC FH Krems