Commit 4a40deac authored by David Trattnig's avatar David Trattnig
Browse files

Improve structure and add meat.

parent c4e7fb0e
<img src=".././aura/meta/raw/master/assets/images/aura-logo.png" width="250" />
# Developer Guide | Architecture
[← Developer Guide | Overview](index.md)
This section holds details on the AURA Architecture.
For more specific documentation please consult the individual `README.md` files [in the relevant projects](https://gitlab.servus.at/aura).
1. [Developer Guide | Architecture](#developer-guide--architecture)
1. [Architecural overview](#architecural-overview)
2. [Component spaces, components and dependencies](#component-spaces-components-and-dependencies)
3. [Diagrams](#diagrams)
1. [Network Diagramm](#network-diagramm)
2. [Simplified Data Model](#simplified-data-model)
4. [AURA API](#aura-api)
5. [Conflict Resolution for the scheduling timetable](#conflict-resolution-for-the-scheduling-timetable)
## Architecural overview
Some of our core organisational and architectural requirements for AURA are:
* **modular architecture**: the whole suite should be made up of modular components which could be exchanged with other custom components
* **transparent API**: every component shall provide a well-documented API through which other components can interact with it, ideally as a REST API
* **reuse of existing components**: we do not want to reinvent the wheel. Several stations already developed single components as free software and we can adapt and build on those
* **modern frameworks**: we do not code from scratch but use modern application development frameworks which provide maintainability as well as security
Out of these requirements we came to an architecture which visually represented
in the components diagram.
> Note: The following component diagram doesn't reflect all the details of the current implementation. It will be updated at some point.
![Diagram illustrating the AuRa components](https://gitlab.servus.at/aura/meta/raw/master/assets/images/components.png "AuRa Components")
## Component spaces, components and dependencies
We suggest to set up the components as in the order above, as
they will partly only be insightful if they interact with each other.
Head over to to each project site. There you will also find a `README.md`
with all necessary infos for the setup:
| | [<img src="https://gitlab.servus.at/aura/meta/raw/master/assets/images/aura-steering.png" width="150" align="left" />](https://gitlab.servus.at/aura/steering) | [<img src="https://gitlab.servus.at/aura/meta/raw/master/assets/images/aura-dashboard.png" width="150" align="left" />](https://gitlab.servus.at/aura/dashboard) | [<img src="https://gitlab.servus.at/aura/meta/raw/master/assets/images/aura-tank.png" width="150" align="left" />](https://gitlab.servus.at/aura/tank) | [<img src="https://gitlab.servus.at/aura/meta/raw/master/assets/images/aura-engine.png" width="150" align="left" />](https://gitlab.servus.at/aura/engine) |
|---|---|---|---|---|
| **Component** | [Steering](https://gitlab.servus.at/aura/steering) | [Dashboard](https://gitlab.servus.at/aura/dashboard) | [Tank](https://gitlab.servus.at/aura/tank) | [Engine](https://gitlab.servus.at/aura/engine) |
| **Dependencies** | | Steering, Tank | Steering | Steering, Tank |
The whole _AuRa_ infrastructure is super flexible in the way it can be setup,
that's why we have started compiling a very opinionated [Installation Guide](docs/administration/installation-guide.md).
There is also an _AuRa_ demo setup hosted by https://o94.at. In case you are
interested for a trial-run, please get in touch.
## Diagrams
### Network Diagramm
Check out the provided [Network Diagrams](../administration/network-diagram.md) on ideas how the individual projects can be deployed within your infrastructure.
### Simplified Data Model
Here's a simplified data model on how data is stored in [Steering](https://gitlab.servus.at/aura/steering).
<a href="assets/images/aura-data-model-simple.png"><img src="assets/images/aura-data-model-simple.png" width="500" /></a>
## AURA API
The AURA API is specified using OpenAPI 3:
* Steering API ([**TODO: Provide OpenAPI 3 Specification**](https://gitlab.servus.at/aura/steering/-/issues/44))
* Tank API ([**TODO: Provide OpenAPI 3 Specification**](https://gitlab.servus.at/aura/tank/-/issues/7))
* Engine API (https://app.swaggerhub.com/apis/AURA-Engine/engine-api/1.0.0).
> Open API for Steering and Tank is work in progress. Meanwhile you can find a rudimentary [API definition](api-definition.md).
## Conflict Resolution for the scheduling timetable
Check out the [Administration | Conflict Resolution Documentation](../administration/conflict-resolution.md) page.
<img src=".././aura/meta/raw/master/assets/images/aura-logo.png" width="250" />
# Developer Guide | Development
[← Developer Guide | Overview](index.md)
Learn how to get started on AURA development.
For more specific documentation please consult the individual `README.md` files [in the relevant projects](https://gitlab.servus.at/aura).
### Coding Conventions
Check out the [Coding Conventions](coding-conventions.md) page.
### AURA CLI
Find out more in the [Administration | CLI documentation](../administration/cli.md).
## Contributing to AURA
Too support the project in some way, check out the [contributions page](contributions.md).
Also, check out the [workflow for bug reports](bug-reports.md).
### Licensing
- All AURA source code is licensed under [GNU Affero General Public License (AGPL) v3.0](https://www.gnu.org/licenses/agpl-3.0.en.html).
- All graphic materials, text and other docs are licensed under [Creative Commons BY-NC-SA v3.0](https://creativecommons.org/licenses/by-nc-sa/3.0/)
By contributing your code you agree to these licences and confirm that you are the copyright owner of the supplied contribution.
\ No newline at end of file
<img src=".././aura/meta/raw/master/assets/images/aura-logo.png" width="250" />
# Developer Guide | Installation
For Development the native installation as outlined in the `README.md` of each project is recommended.
In case you are not developing on some certain project, but need it as a dependency only, you can install it using the Docker Image deployment variant.
> TODO: The Docker and Docker Compose installation variants [are not yet completed](https://gitlab.servus.at/aura/meta/-/issues/56).
> Note: For production we highly recommend to run AURA using Docker and Docker Compose as outlined in the [Administration Guide](../administration/index.md)
It is recommended to clone all projects for example in such folder structure:
```bash
~code/aura/meta
~code/aura/steering
~code/aura/dashboard
~code/aura/engine
~code/aura/engine-api
~code/aura/engine-core
...
```
After that, you need to configure the projects in following order:
**Web Projects**
1. [Steering](https://gitlab.servus.at/aura/steering) - Administration interface for schedules and programme information.
2. [Dashboard](https://gitlab.servus.at/aura/dashboard) - Frontend to manage schedules, program info and audio files.
3. [Tank](https://gitlab.servus.at/aura/tank) - Upload, pre-processing and storage of the audio files.
4. ...
**Playout Projects**
1. [Engine Core](https://gitlab.servus.at/aura/engine) - Playout-engine to deliver the actual radio to the audience.
2. [Engine API](https://gitlab.servus.at/aura/engine) - API Server to provide playlogs and information for the studio clock.
3. [Engine](https://gitlab.servus.at/aura/engine) - Scheduling and remote control for the playout-engine.
4. ...
<img src=".././aura/meta/raw/master/assets/images/aura-logo.png" width="250" />
# Developer Guide | Planning
[← Developer Guide | Overview](index.md)
This is the place to get started with AURA project planning and related workflows.
1. [Developer Guide | Planning](#developer-guide--planning)
1. [Sprint Planning](#sprint-planning)
2. [Planned Versions and Release Criteria](#planned-versions-and-release-criteria)
3. [Release Managment](#release-managment)
## Sprint Planning
*TODO: [Define sprint planning workflow](https://gitlab.servus.at/aura/meta/-/issues/64)*
The current sprint can be looked-up at our [Scrum Board](https://gitlab.servus.at/aura/meta/-/boards).
## Planned Versions and Release Criteria
The project status and current version can be found at the [AURA Wiki: Project Status Page (German)](https://gitlab.servus.at/aura/meta/-/wikis/Projektstatus).
## Release Managment
Get an overview in the [Release Management](dev-releases.md) section.
\ No newline at end of file
# Release Managment
<img src=".././aura/meta/raw/master/assets/images/aura-logo.png" width="250" />
# Developer Guide | Release Management
[← Developer Guide | Overview](index.md)
This section holds details on AURA release management.
1. [Developer Guide | Release Management](#developer-guide--release-management)
1. [SemVer Versioning Scheme](#semver-versioning-scheme)
2. [Current Release](#current-release)
3. [How to perform a release?](#how-to-perform-a-release)
## SemVer Versioning Scheme
Release names are defined according to the [Semantic Versioning 2.0.0](https://gitlab.servus.at/aura/meta/-/issues/25) versioning scheme.
Release names are defined according to the [Semantic Versioning 2.0.0](https://semver.org/) versioning scheme.
## Current Release
......
......@@ -4,157 +4,8 @@
This guide holds all general information for AURA developers. For more specific documentation please consult the individual `README.md` files [in the relevant projects](https://gitlab.servus.at/aura).
1. [Developer Guide](#developer-guide)
1. [Architecture](#architecture)
1. [Architecural overview](#architecural-overview)
2. [Component spaces, components and dependencies](#component-spaces-components-and-dependencies)
2. [Installation](#installation)
3. [Development](#development)
1. [Coding Conventions](#coding-conventions)
2. [Network Diagramm](#network-diagramm)
3. [Simplified Data Model](#simplified-data-model)
4. [AURA CLI](#aura-cli)
5. [AURA API](#aura-api)
6. [Conflict Resolution for the timetable](#conflict-resolution-for-the-timetable)
4. [Planning](#planning)
1. [Sprint Planning](#sprint-planning)
2. [Planned Versions and Release Criteria](#planned-versions-and-release-criteria)
5. [Release Managment](#release-managment)
6. [Contributing to AURA](#contributing-to-aura)
1. [Licensing](#licensing)
## Architecture
### Architecural overview
Some of our core organisational and architectural requirements for AURA are:
* **modular architecture**: the whole suite should be made up of modular components which could be exchanged with other custom components
* **transparent API**: every component shall provide a well-documented API through which other components can interact with it, ideally as a REST API
* **reuse of existing components**: we do not want to reinvent the wheel. Several stations already developed single components as free software and we can adapt and build on those
* **modern frameworks**: we do not code from scratch but use modern application development frameworks which provide maintainability as well as security
Out of these requirements we came to an architecture which visually represented
in the components diagram.
> Note: The following component diagram doesn't reflect all the details of the current implementation. It will be updated at some point.
![Diagram illustrating the AuRa components](https://gitlab.servus.at/aura/meta/raw/master/assets/images/components.png "AuRa Components")
### Component spaces, components and dependencies
We suggest to set up the components as in the order above, as
they will partly only be insightful if they interact with each other.
Head over to to each project site. There you will also find a `README.md`
with all necessary infos for the setup:
| | [<img src="https://gitlab.servus.at/aura/meta/raw/master/assets/images/aura-steering.png" width="150" align="left" />](https://gitlab.servus.at/aura/steering) | [<img src="https://gitlab.servus.at/aura/meta/raw/master/assets/images/aura-dashboard.png" width="150" align="left" />](https://gitlab.servus.at/aura/dashboard) | [<img src="https://gitlab.servus.at/aura/meta/raw/master/assets/images/aura-tank.png" width="150" align="left" />](https://gitlab.servus.at/aura/tank) | [<img src="https://gitlab.servus.at/aura/meta/raw/master/assets/images/aura-engine.png" width="150" align="left" />](https://gitlab.servus.at/aura/engine) |
|---|---|---|---|---|
| **Component** | [Steering](https://gitlab.servus.at/aura/steering) | [Dashboard](https://gitlab.servus.at/aura/dashboard) | [Tank](https://gitlab.servus.at/aura/tank) | [Engine](https://gitlab.servus.at/aura/engine) |
| **Dependencies** | | Steering, Tank | Steering | Steering, Tank |
The whole _AuRa_ infrastructure is super flexible in the way it can be setup,
that's why we have started compiling a very opinionated [Installation Guide](docs/administration/installation-guide.md).
There is also an _AuRa_ demo setup hosted by https://o94.at. In case you are
interested for a trial-run, please get in touch.
## Installation
For Development the native installation as outlined in the `README.md` of each project is recommended.
In case you are not developing on some certain project, but need it as a dependency, you can install it using the Docker Image deployment variant.
> Note: For production we highly recommend to run AURA using Docker and Docker Compose as outlined in the [Administration Guide](../administration/index.md)
It is recommended to clone all projects for example in such folder structure:
```bash
~code/aura/meta
~code/aura/steering
~code/aura/dashboard
~code/aura/engine
~code/aura/engine-api
~code/aura/engine-core
...
```
Then it is recommended to configure the projects in following order:
**Web Projects**
1. [Steering](https://gitlab.servus.at/aura/steering) - Administration interface for schedules and programme information.
2. [Dashboard](https://gitlab.servus.at/aura/dashboard) - Frontend to manage schedules, program info and audio files.
3. [Tank](https://gitlab.servus.at/aura/tank) - Upload, pre-processing and storage of the audio files.
4. ...
**Playout Projects**
1. [Engine Core](https://gitlab.servus.at/aura/engine) - Playout-engine to deliver the actual radio to the audience.
2. [Engine API](https://gitlab.servus.at/aura/engine) - API Server to provide playlogs and information for the studio clock.
3. [Engine](https://gitlab.servus.at/aura/engine) - Scheduling and remote control for the playout-engine.
4. ...
## Development
### Coding Conventions
Check out the [Coding Conventions](coding-conventions.md) page.
### Network Diagramm
Check out the provided [Network Diagrams](network-diagram.md) on ideas how the individual projects can be deployed within your infrastructure.
### Simplified Data Model
Here's a simplified data model on how data is stored in [Steering]().
<a href="assets/images/aura-data-model-simple.png"><img src="assets/images/aura-data-model-simple.png" width="500" /></a>
### AURA CLI
Find out more in the [Administration | CLI documentation](../administration/cli.md).
### AURA API
The AURA API is specified using OpenAPI 3:
* Steering API ([**TODO: Provide OpenAPI 3 Specification**](https://gitlab.servus.at/aura/steering/-/issues/44))
* Tank API ([**TODO: Provide OpenAPI 3 Specification**](https://gitlab.servus.at/aura/tank/-/issues/7))
* Engine API (https://app.swaggerhub.com/apis/AURA-Engine/engine-api/1.0.0).
> Open API for Steering and Tank is work in progress. Meanwhile you can find a rudimentary [API definition](api-definition.md).
### Conflict Resolution for the timetable
Check out the [Administration | Conflict Resolution Documentation](../administration/conflict-resolution.md) page.
## Planning
### Sprint Planning
*TODO: [Define sprint planning workflow](https://gitlab.servus.at/aura/meta/-/issues/64)*
The current sprint can be looked-up at our [Scrum Board](https://gitlab.servus.at/aura/meta/-/boards).
### Planned Versions and Release Criteria
The project status and current version can be found at the [AURA Wiki: Project Status Page (German)](https://gitlab.servus.at/aura/meta/-/wikis/Projektstatus).
## Release Managment
Get an overview in the [Release Management](../releases/index.md) section.
## Contributing to AURA
Too support the project in some way, check out the [contributions page](contributions.md).
### Licensing
- All AURA source code is licensed under [GNU Affero General Public License (AGPL) v3.0](https://www.gnu.org/licenses/agpl-3.0.en.html).
- All graphic materials, text and other docs are licensed under [Creative Commons BY-NC-SA v3.0](https://creativecommons.org/licenses/by-nc-sa/3.0/)
By contributing your code you agree to these licences and confirm that you are the copyright owner of the supplied contribution.
\ No newline at end of file
1. [Developer Guide - Architecture](dev-architecture.md)
2. [Developer Guide - Development](dev-development.md)
3. [Developer Guide - Installation](dev-install.md)
4. [Developer Guide - Planning](dev-planning.md)
5. [Developer Guide - Releases](dev-releases.md)
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment