Merge pull request #306 from dedica-team/develop

Release 0.3.1

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve (removed unneeded parts)
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# How to contribute
+
+We are really glad you're reading this, because we need volunteer developers to help this project come to fruition.
+
+If you haven't already, come find us on [Slack](https://dedica-hacktoberfest.slack.com/). We want you working on things you're excited about.
+
+Here are some important resources:
+
+  * [Contributors](https://github.com/dedica-team/nivio/graphs/contributors) tells you where we are,
+  * [Our project roadmap](https://github.com/dedica-team/nivio/projects/1)
+  * [Issues](https://github.com/dedica-team/nivio/issues)
+  * [Chat](https://dedica-hacktoberfest.slack.com/)
+  * *Readme* both frontend and backend contain readme files (see ./src/main/...)
+
+## Testing
+
+  * For the backend code we test using Jupiter and sometimes using SpringBootTest or WireMock. Use of AssertJ is encouraged.
+  * The frontend is tested using Jest and React Testing library.
+
+## Submitting changes
+
+Please send a [GitHub Pull Request](https://github.com/opengovernment/opengovernment/pull/new/master) with a clear list of what you've done (read more about [pull requests](http://help.github.com/pull-requests/)). 
+
+  * The *develop* branch is the base for all new features.
+  * Always write a clear log message for your commits.
+  * Please include the ticket id in commit messages, if possible.
+  * Make sure that your contribution is well tested.
+  * Try not to introduce new dependencies for common tasks
+
+## Coding conventions
+
+Start reading our code and you'll get the hang of it. We optimize for readability:
+
+  * We think that the Zen Of Python is a good idea and we hate code generation.
+  * In Java we indent using four spaces (Intellij default settings)
+  * In React we indent using two spaces using prettier.
+  * This is open source software. Consider the people who will read your code, and make it look nice for them. 
+
+Thanks,
+the dedica team

Dockerfile

@@ -1,5 +1,5 @@
 # use not slim base image, because libfontmanager needs libfreetype (mfbieber)
-FROM openjdk:11-jre
+FROM adoptopenjdk/openjdk11:x86_64-alpine-jre-11.0.8_10
 
 ENV JAVA_TOOL_OPTIONS="-Xmx400m"
 VOLUME /tmp

backend-architecture-api.puml

@@ -0,0 +1,180 @@
+@startuml
+
+class ApiController {
+    +Index index()
+    +ResponseEntity<LandscapeImpl> landscape(String landscapeIdentifier)
+    +ResponseEntity<Group> group(String landscapeIdentifier, String groupIdentifier)
+    +ResponseEntity<Item> item(String landscapeIdentifier, String groupIdentifier, String itemIdentifier)
+    +ProcessLog create(@RequestBody String body)
+    +ProcessLog indexLandscape(String identifier, String format, String body)
+    +ResponseEntity<ProcessLog> log(String identifier)
+    +ResponseEntity<Set<Item>> search(String identifier, String query)
+    +ResponseEntity<List<FacetResult>> facets(String identifier)
+    +ProcessLog reindex(String landscape)
+}
+
+ApiController o-- LandscapeRepository
+ApiController o-- LandscapeDescriptionFactory
+ApiController o-- InputFormatHandlerFactory
+ApiController o-- Indexer
+
+class LandscapeImpl {
+    -String identifier
+    -String name
+    -String contact
+    -String description
+    -String source
+    -ItemIndex items
+    -LandscapeConfig config
+    -Map<String, GroupItem> groups
+    -ProcessLog processLog
+    -Map<String, String> labels
+    -Map<String, Link> links
+    -String owner
+}
+
+class LandscapeConfig {
+    -boolean greedy = true;
+    -LayoutConfig groupLayoutConfig
+    -LayoutConfig itemLayoutConfig
+    -List<String> groupBlacklist
+    -List<String> labelBlacklist
+    -Branding branding
+    -Map<String, KPIConfig> kpis
+}
+
+class LayoutConfig {
+    -Integer maxIterations
+    -Float forceConstantFactor
+    -Float maxDistanceLimitFactor
+    -Float minDistanceLimitFactor
+}
+
+LandscapeImpl o-- LandscapeConfig
+LandscapeConfig o-- LayoutConfig
+
+class LandscapeRepository {
+    +Optional<LandscapeImpl> findDistinctByIdentifier(String identifier)
+    +void save(LandscapeImpl landscape)
+    +Iterable<LandscapeImpl> findAll()
+}
+
+LandscapeRepository o-- LandscapeImpl
+
+class LandscapeDescriptionFactory {
+    +LandscapeDescription from(Landscape landscape)
+    +LandscapeDescription from(URL url)
+    +LandscapeDescription fromYaml(File file)
+    +LandscapeDescription fromString(String yaml, String origin)
+    +LandscapeDescription fromString(String yaml, URL url)
+}
+
+LandscapeDescriptionFactory -- LandscapeDescription
+
+class LandscapeDescription{
+    -String identifier
+    -String name
+    -String contact
+    -String description
+    -String owner
+    -Map<String, ItemDescription> templates
+    -String source
+    -List<SourceReference> sources
+    -ItemDescriptions itemDescriptions
+    -LandscapeConfig config
+    -boolean isPartial
+    -Map<String, GroupItem> groups;
+    -Map<String, Link> links
+    -Map<String, String> labels
+
+}
+
+class InputFormatHandlerFactory {
+This service returns the correct input format (nivio, k8s...) handler for a SourceReference
+--
+    +InputFormatHandler getInputFormatHandler(SourceReference reference)
+}
+
+class Indexer {
+Triggered by ApplicationEvents fired by observing changes in files through the
+FileSourceReferenceObserver
+--
+    -LandscapeRepository landscapeRepo
+    -InputFormatHandlerFactory formatFactory
+    -ApplicationEventPublisher eventPublisher
+    -LocalServer localServer
+    +ProcessLog reIndex(final LandscapeDescription input)
+    -void runResolvers(LandscapeDescription input, ProcessLog logger, LandscapeImpl landscape)
+}
+
+abstract class Resolver {
+    + {abstract} void process(LandscapeDescription input, LandscapeImpl landscape)
+}
+
+Indexer o-- Resolver
+
+class GroupResolver {
+Resolves the groups in the landscape by examining
+item.group names and adds missing (not pre-configured) groups
+--
+    +process(LandscapeDescription input, LandscapeImpl landscape)
+}
+
+class AppearanceResolver {
+Resolves color and icons for Component, the base for
+landscapes, groups and items.
+--
+    +process(LandscapeDescription input, LandscapeImpl landscape)
+}
+
+class AnotherResolver {
+    some more resolvers are:
+    DiffResolver
+    GroupQueryResolver
+    ItemRelationResolver
+    MagicLabelRelations
+}
+
+Resolver <|-- GroupResolver
+Resolver <|-- AppearanceResolver
+Resolver <|-- AnotherResolver
+
+class FileFetcher {
+    +String readFile(File source)
+    +String get(File file)
+    +String get(URL url)
+    +String get(SourceReference ref)
+    +String get(SourceReference ref, URL baseUrl)
+}
+
+LandscapeDescriptionFactory o-- FileFetcher
+
+interface InputFormatHandler {
+    Processors of input sources must implement this interface
+    +List<String> getFormats()
+    +List<ItemDescription> getDescriptions(SourceReference reference, URL baseUrl)
+    {static} void assignNotNull(ItemDescription existing, ItemDescription increment)
+}
+
+InputFormatHandlerFactory o-- InputFormatHandler
+
+class InputFormatHandlerKubernetes {
+(one implementation shown as an example)
+--
+    +List<String> getFormats()
+    +List<ItemDescription> getDescriptions(SourceReference reference, URL baseUrl)
+    ..
+    -ItemDescription createPodItemDescription(Pod pod)
+    -List<Pod> getPods()
+    -ItemDescription createDescriptionFromService(Service kubernetesService, List<ItemDescription> pods)
+    -List<ItemDescription> createDescriptionsFromPod(Pod pod, ItemDescription podItem)
+    -ItemDescription createVolumeDescription(String group, Volume volume, Pod pod, ItemDescription podItem)
+    -void setConditionsAndHealth(PodStatus status, ItemDescription podItem)
+    -String getGroup(HasMetadata hasMetadata)
+    -KubernetesClient getClient(String context)
+}
+
+InputFormatHandler <|--  InputFormatHandlerKubernetes
+
+
+@enduml

readme.md

@@ -81,4 +81,30 @@ Clone nivio, build and run a Docker image:
 
   Open http://localhost:8080
 
-  If you want to contribute to our frontend, read further into our [Frontend Readme](https://github.com/dedica-team/nivio/tree/develop/src/main/app)
+  If you want to contribute to our frontend, read further into our [Frontend Readme](https://github.com/dedica-team/nivio/tree/develop/src/main/app)
+
+**Nivio Backend Architecture**
+
+If you want to contribute to our backend, maybe the following diagram is of use to you. It shows some of the most important classes and 
+interfaces. It is supposed to give you an idea on how the backend is structured, but note that not all details are displayed:
+
+ ![layoutedArtifact graph](backend_architecture_api.png)
+
+ If you use the `ApiController` as the entry point to the backend, you can see that it retrieves information and triggers events
+  to the most important parts of the application. 
+
+The `LandscapeRespository` gives access to the stored landscapes.
+
+The `LandscapeDescriptionFactory` is used to generate a `LandscapeDescription` from various sources, such as a `String` input, 
+or e.g. from a yaml file. 
+
+This `LandscapeDescription` has to be enriched with the `ItemDescription` for all items in the landscape.
+This is managed by the `InputFormatHandler`, which are able to read several input formats such as e.g. kubernetes files, or the
+nivio description format. Access to these handlers is managed by the `InputFormatHandlerFactory`.
+
+To actually create a landscape, the `Indexer` is used. This is able to compute the landscape graph from a `LandscapeDescription`.
+The `Indexer` uses several `Resolver` to resolve groups and item relations in landscapes and e.g. the appearance of the graph.
+
+The `Indexer` can be triggered either directly through the `ApiController` to index or reindex a landscape, or it is triggered
+by an observer mechanism on files. These are the files located under the path provided through the `SEED` environment variable.
+

src/main/app/src/App.tsx

@@ -1,12 +1,12 @@
 import React from 'react';
 import { HashRouter as Router, Switch, Route } from 'react-router-dom';
 
-import LandscapeOverview from './Components/LandscapeComponent/LandscapeOverview/LandscapeOverview';
-import LandscapeMap from './Components/LandscapeComponent/LandscapeMap/LandscapeMap';
-import Man from './Components/ManComponent/Man';
-import Layout from './Components/LayoutComponent/Layout';
-import Events from './Components/EventComponent/Events';
-import LandscapeDashboard from './Components/LandscapeComponent/LandscapeDashboard/LandscapeDashboard';
+import LandscapeOverview from './Components/Landscape/Overview/Overview';
+import LandscapeMap from './Components/Landscape/Map/Map';
+import Man from './Components/Manual/Man';
+import Layout from './Components/Layout/Layout';
+import Events from './Components/Events/Events';
+import LandscapeDashboard from './Components/Landscape/Dashboard/Dashboard';
 import { Routes } from './interfaces';
 
 import './App.scss';

src/main/app/src/Components/EventComponent/Events.tsx → src/main/app/src/Components/Events/Events.tsx

@@ -1,7 +1,7 @@
 import React, { useState, useEffect, useCallback } from 'react';
 import './Events.scss';
-import TitleBar from '../TitleBarComponent/TitleBar';
-import LevelChip from '../LevelChipComponent/LevelChip';
+import TitleBar from '../TitleBar/TitleBar';
+import LevelChip from '../LevelChip/LevelChip';
 import { get } from '../../utils/API/APIClient';
 
 interface Entry {

src/main/app/src/Components/ModalComponent/GenericModal.tsx → src/main/app/src/Components/GenericModal/GenericModal.tsx

@@ -8,6 +8,7 @@ interface IGenericModalProps {
 }
 
 /**
+ * CURRENTLY UNUSED
  * Creates a React Modal with given modalContent, that can be closed via button, esc or by clicking outside of the overlay
  * @param modalContent Content that should be displayed
  */