Introduction and Goals

Introduction and Goals

arc42 Overview

Application Goals

The application is an application of modern software engineering principles.

The essential features are used to implement all acquisition, project management and financial process of an agile software consulting company.

The smoke test is to run the tangly processes on the ERP solution.

User Journey

Leads

After meeting a prospect at a conference, I create a lead. I follow up with the lead and add the information in the text of the lead.

Opportunities

Once a lead is qualified, I create a natural entity for the prospect, a legal entity for the company he is working for and an employee for the relation between him and the company. The acquisition process is documented in an opportunity with a set of activities describing our interactions.

Contracts

A successful opportunity generates a contract with the legal entity.

Later on, the contract can be extended with contract extensions. Sometimes new areas of work are identified and new contracts are created.

Work Contracts

A manager can activate the contract and initiate a work contract in the product domain. A product is created and the work contract is assigned to the product. Assignments are created to assign collaborators to the product development.

Collaborators track their work in activities. An activity is a time tracking record with a description, the associated collaborator and the contract.

Dashboards display the progress of the product development. The worked hours are compared with the time budget of the assignments and the work contract.

Invoices

Regularly, work reports are generated to invoice the customer. The reports and the invoices are sent to the customer. Invoices are handled in the invoice domain.

Ledger

Once the invoice is paid, the transaction is booked in the accounting system. The ledger domain is used to manage financial transactions.

Global Requirements

  • Entities shall have a human-readable identifier encoded as a string [1][2].

  • Structured application-specific or market-specific information shall be stored as reference codes [3].

  • Non-structured information is written down as text. Asciidoc is used as a markup language.

  • Changes can be documented as a list of comments.

  • Dynamic data shall be stored as tags. Tags define an application-specific or market-specific ontology [4].

ID Type Description Remarks

req-001

import

As a user, I want to import all data of a domain as a set of TSV files so that I can migrate strategic data.

No dependencies to a database shall exit

req-002

export

As a user, I want to export all data of a domain as a set of TSV files so that I can back up strategic data in a human-readable form.

Human-readable form is necessary for audit. The export format is also used as import format.

req-003

clear

As a user, I can clear all data of a domain so that I can start with a clean system.

Before importing data, the system should be cleared.

Authentication and Authorization

The user shall log in with a username and a password. The tenancy is defined by the domain preceeding the username domain/username.

Authorization is based on roles and is defined per domain.

The following roles are defined:

None

No access to a specific domain.

Restricted User

User has read and write access to the entities he owns. For example, a restricted users has access to his activities.

Read User

User has read access to the entities of a domain.

Write User

User has write access to the entities of a domain.

Admin User

User has write access to the entities of a domain and has access to power user operations. Import, export and clear operations are examples of power user operations.

Quality Goals

Documentation Quality Goals

The architecture documentation shall empower a developer to master the bounded domains and build extensions.

ID Type Explanation

doc-001

Correct

Documentation needs to be accurate and free from errors. Wrong documentation is often worse than no documentation.

doc-002

Current

Documentation needs to be correct over time, reflecting changes performed upon code, infrastructure or interfaces of the system.

doc-003

Understandable

Documentation needs to be understood by the intended audience.

doc-004

Relevant

With respect to structure, form and content, documentation shall be relevant for the tasks of its audience.

doc-005

Referencable

Use a consistent numbering schema for headings, diagrams, and tables.

doc-006

Proper language

Use proper language, correct spelling and grammar, active voice, positive statements and short sentences.

doc-007

Maintainable

Maintainability is key to keeping documentation current.

doc-008

Easy to find

Documentation itself should be easy to find whenever needed. Its content should be easily navigable and searchable.

doc-009

Versioned

As the system evolves, so will your documentation, without losing its history

doc-010

Tooling support

Focus on content, reduce time needed for tool-setup

doc-011

Continuously updated

Make it a habit to maintain and expand the documentation with every relevant change in your system.

doc-012

Relevant

Documentation should be written in a public domain format. Multiple public tools should support writing in the selected format.

doc-013

Relevant

Documentation should be searchable to easily access topics.

The current approach is arc42 structure, C4 Model and UML diagrams to document the design. The content is written in Asciidoc format. The documentation is published as a static website using Hugo and Docsy.

The Java source code is documented with Javadoc. Source code in other programming languages is documented with Doxygen.

Categories of Quality Requirements

Stakeholders

Role Relevance Expectations

Open Source Developer

Important

wants to extend the application with functions required for a specific market or user segment.

Company Prospect

Important

looking for a portfolio to show competencies in areas, he is interested in work with us.

Closed Source Developer

Relevant

wants to extend the application with functions she could sell to her customers.

Blog Reader

Relevant

interested to explore a concept discussed in a blog article and exemplary realized in the application.

Application user

Relevant

wants to understand decisions and their impact on the product value or costs.

Bachelor Student

Interesting

wants to use components for semester projects and understand a specific aspect of the design.

The ERP is developed using an open source approach. Development capabilities are dependent on the goodwill and availability of active committers.

Domain Concepts

A service company provides services to customers to build products.

Products Domain

The company develops a product with the customer. A product has a duration.

Multiple work contracts provide a time budget for the development of a specific product. A work contract has a duration. A work contract is a view of an existing commercial contract. The relation is defined through the identifier of the commercial contract.

Employees are assigned to develop the product. The assignment is paid through a work contract time budget. An assignment has a duration, and a product.

The work performed for an assignment is documented through the activities of a collaborator.

Customer Domain

The company has commercial contracts with customers. A commercial contract is a legal agreement between the company and a customer. It should be immutable.

A customer is a legal entity. A contract can be extended with contract extensions.

Invoices Domain

The company sends invoices to customers based on a contract.

Business Rules

The contract date range is in the range of the product time range. The assignment date range is in the range of the contract time range.

The sum of all efforts for all assignments per contract should be comparable with the time budget of the contract.

The sum of all invoices for a contract should be below the contract amount.

Links