Skip to content

Commit

Permalink
Merge pull request #19 from Arquisoft/documentation_jonathan
Browse files Browse the repository at this point in the history 
Documentation jonathan revisada
  • Loading branch information
@alegarman2002
alegarman2002 authored Feb 16, 2024
2 parents b51ae3a + 3062a57 commit 872d378
Show file tree
Hide file tree
Showing 3 changed files with 44 additions and 94 deletions.
Binary file added docs/images/03-deployment-diagram-EN.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
70 changes: 35 additions & 35 deletions docs/src/02_architecture_constraints.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,47 +1,47 @@
[[section-architecture-constraints]]
== Architecture Constraints

=== Technical Constraints
=== Technical constraints

[cols="1,2", options="header"]
|=========================================================================================================================================================================================================
| Constraint | Explanation
| Docker | The application will operate within a Docker environment.
| GitHub | We'll leverage GitHub as our remote repository for project development, task delegation among team members, and version control. GitHub streamlines communication and project organization.

|=========================================================================================================================================================================================================

=== Organizational Constraints

[cols="1,2", options="header"]
|==========================================================================================================================================================================================================================================================
| Constraint | Explanation
| Size of the team | The team comprises six individuals.
| Meetings | Weekly meetings are scheduled to discuss task organization during each laboratory class session. In the event of requiring an extraordinary meeting, various tools such as WhatsApp or Discord are employed to coordinate effectively.
| Testing | Various scenarios will be explored to ensure the app's functionality is tested. We'll employ a range of techniques to maximize test coverage, striving for comprehensive assessment.
| Experience | Team members possess limited experience with the diverse technologies being employed.
|==========================================================================================================================================================================================================================================================


=== Conventions

[cols="1,2", options="header"]
[cols="2,4" options="header"]
|===
| Constraint | Explanation
|Constraint |Explanation

|*OS/Browser Independence* |The project must be available to the maximum amount of users feasible. That includes support for mainstream OSs (_Windows_, _Linux_, _MacOS_) and browsers. (_Chrome_, _Safari_, _Firefox_, _Edge_)
|*Usage of _REACT_* |The _REACT JS_ framework will be used to develop the front-end of the project.
|*Docker* | The application will operate within a Docker environment.
|*Version Control* |In order of the project to be graded adequately, it must use _GitHub_ as its version control software. The contributions of each team member and agreements reached must be easily traceable.
|*Continuous integration and delivery* |The development must progress through frequent integration of small changes into the main branch. New features must be automatically deployed with ease. (In our case, using _Docker_)

| Documentation
| The documentation must adhere to the Arc42 method, ensuring it is clear, simple, and effective.
|===

| Accessibility
| The application should be user-friendly, allowing all individuals to navigate effortlessly, irrespective of any disabilities, ensuring inclusivity for all users.
=== Organizational constraints

| Programming Language conventions
| We ought to follow the conventions specific to the programming languages we're employing.
[cols="2,7" options="header"]
|===
|Constraint |Explanation

|*Time* |The team has to complete the project during the semester.
|*Team size* |The development teams must be composed of 5-7 members. In our case, the final team is composed of 6 members.
|*Budget* |No budget is provided for the development, so any costs that may arise have to be covered by the development team.
|*Deliverables* |Along the development process, the team must prepare deliverables set for certain dates, consisting of documentation and/or application prototypes.
|*Team meetings* |In order to plan the development of the project, as well as to assign tasks and make design decisions, the team will participate in several meetings. These meetings can be done in and out of the classroom, as needed. A record must be created for every meeting, summarizing the progress made.
|*Project testing* |The development team must test acceptable coverage of the project using different methods (_unit testing_, _integration testing_, _acceptance testing_... etc.)
|*Knowledge* |There are many aspects of the development of this project that are foreign to some of us (usage of _REACT_, deployments, microsystems architecture... etc.) so some research is required to keep up.
|===

| Clean Code
| The code in the application must be meticulously crafted and neat, with a focus on readability and maintainability.
=== Conventions

| Mircroservices
| The application will be divided into microservices to facilitate its development.
[cols="2,4" options="header"]
|===
|Constraint |Explanation

|*Use of English* |The totality of the project must be written in English, as to facilitate its understanding internationally.
|*Programming Language conventions* | We ought to follow the conventions specific to the programming languages we're employing.
|*Documentation format* |The documentation must adhere to the Arc42 method, ensuring it is clear, simple, and effective.
|*Clean code* |In order to ease the understanding and maintenance of the project, all code written must be organized, descriptive and easy to read.
|*Accesibility* |The application should be user-friendly, allowing all individuals to navigate effortlessly, irrespective of any disabilities, ensuring inclusivity for all users.
|*Microservices* | The application will be divided into microservices to facilitate its development.
|===

=======
68 changes: 9 additions & 59 deletions docs/src/03_system_scope_and_context.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,73 +3,23 @@ ifndef::imagesdir[:imagesdir: ../images]
[[section-system-scope-and-context]]
== System Scope and Context


[role="arc42help"]
****
.Contents
System scope and context - as the name suggests - delimits your system (i.e. your scope) from all its communication partners
(neighboring systems and users, i.e. the context of your system). It thereby specifies the external interfaces.
If necessary, differentiate the business context (domain specific inputs and outputs) from the technical context (channels, protocols, hardware).
.Motivation
The domain interfaces and technical interfaces to communication partners are among your system's most critical aspects. Make sure that you completely understand them.
.Form
Various options:
* Context diagrams
* Lists of communication partners and their interfaces.
.Further Information
See https://docs.arc42.org/section-3/[Context and Scope] in the arc42 documentation.
****


=== Business Context

[role="arc42help"]
****
.Contents
Specification of *all* communication partners (users, IT-systems, ...) with explanations of domain specific inputs and outputs or interfaces.
Optionally you can add domain specific formats or communication protocols.
.Motivation
All stakeholders should understand which data are exchanged with the environment of the system.
.Form
All kinds of diagrams that show the system as a black box and specify the domain interfaces to communication partners.
Alternatively (or additionally) you can use a table.
The title of the table is the name of your system, the three columns contain the name of the communication partner, the inputs, and the outputs.
****
[cols=3 options="header"]
|===
|Entity |Input |Output

**<Diagram or Table>**
|*User* | App usage and experience. | The user will introduce and send its credentials every time it creates a new account or logs into an existing one.
|*WebApp* | User data and input, as well as external API calls received. | Handled API calls, sent to their respective microservice in order to be processed and answered.
|*Wikidata* |Calls to Wikidata's REST API asking for certain data, which will be used to construct the questions. | Said data. Its format may vary, according to the necessities of the questions generator.

**<optionally: Explanation of external domain interfaces>**
|===

=== Technical Context

[role="arc42help"]
****
.Contents
Technical interfaces (channels and transmission media) linking your system to its environment. In addition a mapping of domain specific input/output to the channels, i.e. an explanation which I/O uses which channel.
.Motivation
Many stakeholders make architectural decision based on the technical interfaces between the system and its context. Especially infrastructure or hardware designers decide these technical interfaces.
.Form
E.g. UML deployment diagram describing channels to neighboring systems,
together with a mapping table showing the relationships between channels and input/output.
****

**<Diagram or Table>**

**<optionally: Explanation of technical interfaces>**
The following diagram represents the general structure of the project, as well as the communication channels between various system components. It shows communication to external sources, as well as communications between the various microsystems.

**<Mapping Input/Output to Channels>**
image::03-deployment-diagram-EN.png[]

0 comments on commit 872d378

Please sign in to comment.