allucanget/calminer-docs
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add project documentation and architecture details

Browse Source 
- Create .gitignore to exclude specific project files and directories.
- Add CONTRIBUTING.md with guidelines for contributing to the project.
- Update README.md to reflect changes in usage section and contact information.
- Introduce 08_concepts.md outlining cross-cutting concepts in the architecture.
- Add 02_data_model.md detailing the data model and relationships.
- Implement 03_security.md to describe security measures and practices.
- Establish 08_ui_design.md for user interface design principles.
- Document quality requirements in 10_quality_requirements.md.
- Identify risks and technical debts in 11_technical_risks.md.
- Create a glossary in 12_glossary.md for project-specific terms.
- Include about-arc42.md to explain the arc42 documentation template.
- Define price calculation variables and formula in price_calculation.md.
- Introduce ADR template in adr.md for documenting architecture decisions.
This commit is contained in:
zwitschi
2025-11-09 13:17:19 +01:00
parent 913746b21d
commit 1af654de1f
13 changed files with 1163 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

246
architecture/08_concepts.md Normal file
View File

@@ -0,0 +1,246 @@
# Cross-cutting Concepts
CalMiner aims to provide a comprehensive platform for mining project scenario analysis, enabling stakeholders to make informed decisions based on data-driven insights. This document outlines the key cross-cutting concepts that underpin the architecture of the CalMiner system.
## Table of Contents
- [Cross-cutting Concepts](#cross-cutting-concepts)
- [Table of Contents](#table-of-contents)
- [Multitenancy](#multitenancy)
- [Mandators](#mandators)
- [Data Isolation](#data-isolation)
- [Configuration Management](#configuration-management)
- [Data Model](#data-model)
- [Security](#security)
- [Authentication and Authorization](#authentication-and-authorization)
- [Authentication](#authentication)
- [Authorization](#authorization)
- [Session Management](#session-management)
- [Token Expiration](#token-expiration)
- [Multi-Factor Authentication (MFA)](#multi-factor-authentication-mfa)
- [Error Handling and Logging](#error-handling-and-logging)
- [Centralized Logging](#centralized-logging)
- [Error Categorization](#error-categorization)
- [Graceful Degradation](#graceful-degradation)
- [Alerting and Monitoring](#alerting-and-monitoring)
- [Log Retention Policies](#log-retention-policies)
- [Performance Optimization](#performance-optimization)
- [Caching](#caching)
- [Asynchronous Processing](#asynchronous-processing)
- [Database Indexing](#database-indexing)
- [Load Balancing](#load-balancing)
- [Scalability Strategies](#scalability-strategies)
- [Horizontal Scaling](#horizontal-scaling)
- [Vertical Scaling](#vertical-scaling)
- [Microservices Architecture](#microservices-architecture)
- [Load Testing](#load-testing)
- [User Interface Design Principles](#user-interface-design-principles)
- [Notification System](#notification-system)
- [Notification Channels](#notification-channels)
- [Configurable Preferences](#configurable-preferences)
- [Event Triggers](#event-triggers)
- [Delivery Reliability](#delivery-reliability)
- [Audit Trail](#audit-trail)
- [Data Integration](#data-integration)
- [API Integration](#api-integration)
- [Data Ingestion](#data-ingestion)
- [Data Transformation](#data-transformation)
- [Data Synchronization](#data-synchronization)
- [Error Handling](#error-handling)
- [Reporting and Analytics](#reporting-and-analytics)
- [Data Visualization](#data-visualization)
- [Custom Reports](#custom-reports)
- [Real-time Analytics](#real-time-analytics)
- [Historical Analysis](#historical-analysis)
## Multitenancy
The Calminer system is designed to support multitenancy, allowing multiple independent users or organizations (tenants) to share the same application instance while maintaining data isolation and security.
### Mandators
Each tenant is represented by a Mandator entity, which encapsulates all data and configurations specific to that tenant.
### Data Isolation
The architecture ensures that data belonging to different tenants is isolated, preventing unauthorized access between tenants.
### Configuration Management
Each tenant can have customized settings and preferences, managed through the Mandator entity.
## Data Model
The system employs a relational data model to manage and store information efficiently. The primary entities include Users, Projects, Datasets, and Results. Each entity is represented as a table in the database, with relationships defined through foreign keys.
A detailed [Data Model](08_concepts/02_data_model.md) documentation is available.
All data interactions are handled through the [Data Access Layer](05_building_block_view.md#data-access-layer), ensuring consistency and integrity across operations.
## Security
The Calminer system incorporates robust security measures to protect sensitive data and ensure compliance with different industry and regulatory standards, such as GDPR or ISO/IEC 27001.
Within the system, security is enforced through multiple layers, including data encryption, access controls, audit logging, vulnerability management, and compliance monitoring.
A comprehensive [Security Concept](08_concepts/03_security.md) is being developed as well.
## Authentication and Authorization
The system utilizes a secure authentication mechanism to verify user identities and manage access to resources.
### Authentication
Users authenticate using secure methods, such as OAuth 2.0 or JWT tokens, to ensure the legitimacy of access requests.
### Authorization
Access to resources is controlled through role-based permissions, ensuring users can only access data and functionalities relevant to their roles.
### Session Management
User sessions are managed securely, with mechanisms in place to prevent session hijacking and ensure session integrity.
### Token Expiration
Access tokens have a limited lifespan and are refreshed periodically to enhance security.
### Multi-Factor Authentication (MFA)
The system supports MFA to provide an additional layer of security during user authentication.
## Error Handling and Logging
The system implements a comprehensive error handling and logging strategy to ensure reliability and facilitate troubleshooting.
### Centralized Logging
All application logs are centralized to a logging service, enabling efficient monitoring and analysis of system behavior.
### Error Categorization
Errors are categorized into different types (e.g., client errors, server errors) to facilitate targeted handling and resolution.
### Graceful Degradation
The system is designed to handle errors gracefully, providing meaningful feedback to users without exposing sensitive information.
### Alerting and Monitoring
The system includes mechanisms for alerting administrators about critical errors and monitoring system health.
### Log Retention Policies
Logs are retained for a specified period to comply with regulatory requirements and support forensic analysis.
## Performance Optimization
The system is designed with performance optimization strategies to ensure efficient operation and responsiveness.
### Caching
Frequently accessed data is cached to reduce database load and improve response times.
### Asynchronous Processing
Time-consuming operations are handled asynchronously to prevent blocking user interactions.
### Database Indexing
Appropriate indexing strategies are implemented to optimize query performance.
### Load Balancing
Traffic is distributed across multiple servers to ensure optimal resource utilization and minimize latency.
## Scalability Strategies
The system is architected to scale efficiently in response to varying workloads and user demands.
### Horizontal Scaling
The system can add more machines or instances to handle increased load, distributing traffic and processing across multiple nodes.
### Vertical Scaling
Individual components can be upgraded with more resources (CPU, memory) to improve performance without changing the overall architecture.
### Microservices Architecture
The system is designed as a collection of loosely coupled services, allowing for independent scaling of different components based on demand.
### Load Testing
Regular load testing is conducted to identify bottlenecks and ensure the system can handle expected traffic patterns.
## User Interface Design Principles
To ensure a consistent and user-friendly experience, the Calminer system adheres to established user interface design principles. A detailed [user interface (UI)](08_concepts/08_ui_design.md) design principles document is available for reference.
## Notification System
The system includes a notification mechanism to inform users about important events and updates.
### Notification Channels
The system supports multiple channels for notifications, including email, SMS, and in-app alerts.
### Configurable Preferences
Users can customize their notification preferences, selecting the types of notifications they wish to receive and the channels through which they are delivered.
### Event Triggers
Notifications are triggered by specific events within the system, such as project updates, data processing completions, or system alerts.
### Delivery Reliability
The notification system is designed to ensure reliable delivery of messages, with retry mechanisms in place for failed attempts.
### Audit Trail
A record of all sent notifications is maintained for auditing purposes and to track user engagement.
## Data Integration
The Calminer system is designed to integrate seamlessly with various external data sources and services.
### API Integration
The system can connect to external APIs to fetch or send data as needed.
### Data Ingestion
Mechanisms are in place to ingest data from various sources, including databases, file systems, and streaming platforms.
### Data Transformation
The system can transform data into the required format for processing and analysis.
### Data Synchronization
Regular synchronization processes ensure that data remains consistent across all integrated systems.
### Error Handling
Robust error handling mechanisms are implemented to manage integration failures and ensure data integrity.
## Reporting and Analytics
The Calminer system includes comprehensive reporting and analytics capabilities to support data-driven decision-making.
### Data Visualization
The system provides tools for visualizing data through charts, graphs, and dashboards, making it easier to identify trends and insights.
### Custom Reports
Users can create custom reports based on specific criteria, allowing for tailored analysis of project performance and resource utilization.
### Real-time Analytics
The system supports real-time data processing and analytics, enabling users to access up-to-date information and respond quickly to changing conditions.
### Historical Analysis
The system maintains a history of key metrics and events, allowing for retrospective analysis and identification of long-term trends.

529
architecture/08_concepts/02_data_model.md Normal file
View File

@@ -0,0 +1,529 @@
# Data Model
The data model for the system is designed to capture the essential entities and their relationships involved in mining projects. Each entity is represented as a table in the relational database, with attributes defining their properties and foreign keys establishing relationships between them.
## Table of Contents
- [Data Model](#data-model)
- [Table of Contents](#table-of-contents)
- [Relationships Diagram](#relationships-diagram)
- [User](#user)
- [User Diagram](#user-diagram)
- [User Roles](#user-roles)
- [System Administrator](#system-administrator)
- [Mandator Administrator](#mandator-administrator)
- [Project Manager](#project-manager)
- [Standard User](#standard-user)
- [Permissions](#permissions)
- [Mandator](#mandator)
- [Project](#project)
- [Location](#location)
- [Currency](#currency)
- [Unit](#unit)
- [Mining Technology](#mining-technology)
- [Product Model](#product-model)
- [Quality Metrics](#quality-metrics)
- [Financial Model](#financial-model)
- [Cost Model](#cost-model)
- [CAPEX](#capex)
- [OPEX](#opex)
- [Revenue Model](#revenue-model)
- [Revenue Streams](#revenue-streams)
- [Product Sales](#product-sales)
- [Investment Model](#investment-model)
- [Economic Model](#economic-model)
- [Risk Model](#risk-model)
- [Parameter](#parameter)
- [Scenario](#scenario)
## Relationships Diagram
```mermaid
erDiagram
User ||--o{ UserRole : has
UserRole ||--o{ RolePermission : has
Permission ||--o{ RolePermission : assigned_to
User ||--o{ Mandator : belongs_to
Mandator ||--o{ Project : has_many
Project ||--|| Location : located_at
Project ||--o{ MiningTechnology : uses
Project ||--o{ FinancialModel : has_many
Project ||--o{ Parameter : has_many
Project ||--o{ Scenario : has_many
ProductModel ||--o{ QualityMetric : has
FinancialModel ||--o{ CostModel : includes
FinancialModel ||--o{ RevenueModel : includes
FinancialModel ||--o{ InvestmentModel : includes
FinancialModel ||--o{ EconomicModel : includes
FinancialModel ||--o{ RiskModel : includes
MiningTechnology ||--o{ Parameter : has_many
MiningTechnology ||--o{ QualityMetric : has_many
CostModel ||--|| CAPEX : has
CostModel ||--|| OPEX : has
RevenueModel ||--o{ RevenueStream : has
RevenueModel ||--o{ ProductSale : has
Currency ||--o{ CAPEX : used_in
Currency ||--o{ OPEX : used_in
Currency ||--o{ RevenueStream : used_in
Currency ||--o{ ProductSale : used_in
Unit ||--o{ ProductModel : used_in
Unit ||--o{ QualityMetric : used_in
Unit ||--o{ Parameter : used_in
```
## User
Users are individuals who have access to the Calminer system.
Each User is associated with a single Mandator and can be assigned to multiple Projects under that Mandator. Users have specific roles and permissions that determine their level of access within the system.
### User Diagram
```mermaid
erDiagram
User {
string UserID PK
string Name
string Email
string PasswordHash
datetime CreatedAt
datetime UpdatedAt
datetime LastLogin
boolean IsActive
}
```
### User Roles
Users can have different roles within the Calminer system, which define their permissions and access levels.
```mermaid
erDiagram
User ||--o{ UserRole : has
UserRole {
string RoleID PK
string RoleName
string Description
}
```
#### System Administrator
The System Administrator role is a special user role that has elevated privileges across the entire Calminer system. This role is responsible for managing system settings, configurations, managing Mandators, user accounts, and overall system maintenance.
#### Mandator Administrator
The Mandator Administrator role is a special user role assigned to individuals who manage a specific Mandator. This role has the authority to oversee Users and Projects within their Mandator, including user assignments and project configurations.
#### Project Manager
The Project Manager role is responsible for overseeing specific Projects within a Mandator. This role has permissions to manage project settings, assign Users to the Project, and monitor project progress.
#### Standard User
The Standard User role can participate in Projects assigned to them but has limited access to administrative functions.
### Permissions
Permissions are defined based on user roles, determining what actions a user can perform within the system. Permissions include:
- View Projects
- Edit Projects
- Manage Users
- Configure System Settings
- Access Reports
- Run Simulations
- Manage Financial Models
- Export Data
- Import Data
- View Logs
- Manage Notifications
- Access API
Permissions are assigned to roles, and users inherit permissions based on their assigned roles. For this purpose, a helper entity `RolePermission` is defined to map roles to their respective permissions.
The Permissions entity (and RolePermission entity) is defined as follows:
```mermaid
erDiagram
RolePermission {
string RoleID FK
string PermissionID FK
}
Permission {
string PermissionID PK
string PermissionName
string Description
}
UserRole ||--o{ RolePermission : has
Permission ||--o{ RolePermission : assigned_to
```
## Mandator
The Mandator entity represents organizational units or clients using the system. A Mandator can have multiple Users and Projects associated with it.
```mermaid
erDiagram
Mandator {
string MandatorID PK
string Name
string ContactInfo
datetime CreatedAt
datetime UpdatedAt
boolean IsActive
}
```
## Project
The Project entity encapsulates the details of mining projects. Attributes include ProjectID, ProjectName, Description, LocationID (linking to the Location entity), CreationDate, and OwnerID (linking to the User entity). Projects can have multiple Datasets associated with them.
```mermaid
erDiagram
Project {
string ProjectID PK
string ProjectName
string Description
string LocationID FK
datetime CreationDate
string OwnerID FK
string Status
datetime StartDate
}
```
## Location
The Location entity represents the geographical context of the data being mined. Locations can be linked to multiple Projects.
```mermaid
erDiagram
Location {
string LocationID PK
string Name
string Description
string Coordinates
string Region
string Country
}
```
## Currency
The Currency entity defines the monetary units used in the system. Currency is used when dealing with any monetary values in Projects or Results.
```mermaid
erDiagram
Currency {
string CurrencyID PK
string Code
string Name
string Symbol
datetime CreatedAt
datetime UpdatedAt
boolean IsActive
}
```
## Unit
The Unit entity defines measurement units used in the system. Units are essential for standardizing data representation across mining projects, financial models, and results.
```mermaid
erDiagram
Unit {
string UnitID PK
string Name
string Symbol
string Description
}
```
## Mining Technology
The Mining Technology entity encompasses the various tools and techniques used in data mining projects. A Mining Project typically utilizes one specific Mining Technology.
```mermaid
erDiagram
MiningTechnology {
string TechnologyID PK
string Name
string Description
}
```
## Product Model
The Product Model entity captures the details of products extracted or processed in mining projects. It includes attributes such as ProductID, Name, Type and UnitID (linking to the Unit entity). A Product Model can have multiple Quality Metrics associated with it.
```mermaid
erDiagram
ProductModel {
string ProductID PK
string Name
string Type
string UnitID FK
}
ProductModel ||--o{ QualityMetric : has
Unit ||--o{ ProductModel : used_in
Unit ||--o{ QualityMetric : used_in
```
### Quality Metrics
Quality Metrics define the standards and specifications for products derived from mining projects. These metrics ensure that products meet industry and regulatory requirements.
For example, Quality Metrics for a mineral product may include:
- Purity Level
- Moisture Content
- Impurity Levels
- Grain Size Distribution
- Chemical Composition
- Physical Properties
These metrics are essential for assessing the value and usability of the products in various applications and markets.
```mermaid
erDiagram
QualityMetric {
string MetricID PK
string Name
string Description
float MinValue
float MaxValue
string UnitID FK
string AssociatedProductID FK
}
ProductModel ||--o{ QualityMetric : has
Unit ||--o{ QualityMetric : used_in
```
## Financial Model
The Financial Model entity captures the economic aspects of mining projects. The Financial Model includes various sub-models and components that detail costs, revenues, investments, and risks associated with mining projects. Financial Models are the basis for Scenario analyses within Projects.
```mermaid
erDiagram
FinancialModel {
string ModelID PK
string Name
string Description
string AssociatedProjectID FK
}
```
### Cost Model
The Cost Model details the expenses associated with mining projects, including capital expenditures (CAPEX) and operational expenditures (OPEX).
- CAPEX: Initial costs for equipment, infrastructure, and setup.
- OPEX: Ongoing costs for labor, maintenance, and operations.
```mermaid
erDiagram
CostModel {
string ModelID PK
string Name
string Description
string AssociatedProjectID FK
}
CAPEX {
string CAPEXID PK
float EquipmentCost
float InfrastructureCost
float SetupCost
float ContingencyCost
float TotalCAPEX
string CurrencyID FK
}
OPEX {
string OPEXID PK
float LaborCost
float MaterialsCost
float EquipmentRentalCost
float UtilitiesCost
float MaintenanceCost
float TotalOPEX
string CurrencyID FK
}
FinancialModel ||--o{ CostModel : includes
CostModel ||--|| CAPEX : has
CostModel ||--|| OPEX : has
Currency ||--o{ CAPEX : used_in
Currency ||--o{ OPEX : used_in
```
#### CAPEX
For a calculation of Capital Expenditures (CAPEX), the following attributes are included:
- EquipmentCost
- InfrastructureCost
- SetupCost
- ContingencyCost
- TotalCAPEX
- CurrencyID (Foreign Key to Currency)
#### OPEX
For a calculation of Operational Expenditures (OPEX), the following attributes are included:
- LaborCost
- MaterialsCost
- EquipmentRentalCost
- UtilitiesCost
- MaintenanceCost
- TotalOPEX
- CurrencyID (Foreign Key to Currency)
### Revenue Model
The Revenue Model outlines the income generated from mining projects. It includes various revenue streams and product sales.
```mermaid
erDiagram
RevenueModel {
string ModelID PK
string Name
string Description
string AssociatedProjectID FK
}
FinancialModel ||--o{ RevenueModel : includes
RevenueStream {
string RevenueStreamID PK
string Name
string Description
float Amount
string CurrencyID FK
string AssociatedRevenueModelID FK
string Frequency
datetime StartDate
datetime EndDate
boolean IsRecurring
}
FinancialModel ||--o{ RevenueModel : includes
RevenueModel ||--o{ RevenueStream : has
Currency ||--o{ RevenueStream : used_in
```
#### Revenue Streams
Revenue streams can include product sales, service fees, and other income sources related to the mining project.
```mermaid
erDiagram
RevenueStream {
string RevenueStreamID PK
string Name
string Description
float Amount
string CurrencyID FK
string AssociatedRevenueModelID FK
string Frequency
datetime StartDate
datetime EndDate
boolean IsRecurring
}
```
#### Product Sales
Mining product sales represent the primary revenue stream for most mining projects. Product sales revenue is calculated based on the quantity of product sold, price per unit, and any applicable adjustments for quality or other factors like penalties for impurities. Also see [Price Calculation](/specifications/price_calculation.md) for more details.
```mermaid
erDiagram
ProductSale {
string SaleID PK
string ProductID FK
float QuantitySold
float PricePerUnit
float TotalRevenue
string CurrencyID FK
datetime SaleDate
}
ProductModel ||--o{ ProductSale : has
Currency ||--o{ ProductSale : used_in
```
### Investment Model
The Investment Model focuses on the funding and financial backing of mining projects. It includes details about investors, investment amounts, and dates.
```mermaid
erDiagram
InvestmentModel {
string InvestmentID PK
string InvestorID FK
string ProjectID FK
float Amount
datetime InvestmentDate
}
FinancialModel ||--o{ InvestmentModel : includes
```
### Economic Model
The Economic Model assesses the overall economic viability and impact of mining projects. Economic indicators such as Net Present Value (NPV), Internal Rate of Return (IRR), and Payback Period are calculated within this model.
```mermaid
erDiagram
EconomicModel {
string ModelID PK
string Name
string Description
string AssociatedProjectID FK
}
FinancialModel ||--o{ EconomicModel : includes
```
### Risk Model
The Risk Model identifies and evaluates potential risks associated with mining projects. It includes risk factors, their probabilities, and potential impacts on project outcomes.
```mermaid
erDiagram
RiskModel {
string ModelID PK
string Name
string Description
string AssociatedProjectID FK
}
FinancialModel ||--o{ RiskModel : includes
```
## Parameter
Parameters are configurable inputs used within Financial Models to simulate different economic conditions and scenarios for mining projects. Each Parameter has a name, type, default value, and is linked to a specific Technology.
```mermaid
erDiagram
Parameter {
string ParameterID PK
string Name
string Type
string DefaultValue
string Description
string AssociatedTechnologyID FK
}
```
## Scenario
A Scenario represents a specific configuration or analysis case within a Project. Scenarios utilize various Financial Models and Parameters to simulate different outcomes for mining projects.
```mermaid
erDiagram
Scenario {
string ScenarioID PK
string Name
string Description
string AssociatedProjectID FK
}
```

101
architecture/08_concepts/03_security.md Normal file
View File

@@ -0,0 +1,101 @@
# Security Concept
CalMiner places a strong emphasis on security to protect sensitive data and ensure the integrity of the system. The following security measures and practices are implemented to safeguard the platform:
## Data Encryption
All sensitive data is encrypted at rest and in transit to prevent unauthorized access.
## Access Controls
Role-based access controls (RBAC) are implemented to restrict data access based on user roles and responsibilities.
Also see [Authentication and Authorization](08_concepts.md#authentication-and-authorization) and the [Data Model](08_02_data_model.md#user-roles) sections.
## Audit Logging
Comprehensive logging of user activities and system events is maintained for monitoring and auditing purposes. Also see [Error Handling and Logging](08_concepts.md#error-handling-and-logging) section for more details.
## Vulnerability Management
Regular security assessments and updates are conducted to identify and mitigate potential vulnerabilities.
## Compliance
The system adheres to relevant regulatory requirements, such as GDPR, to ensure data privacy and protection.
## Architectural Diagram with Security Layers
```mermaid
architecture-beta
group SecurityLayers[Security Layers]
service FrontendLayer(server)[Frontend Layer] in SecurityLayers
service APILayer(server)[API Layer] in SecurityLayers
service ServiceLayer(server)[Service Layer] in SecurityLayers
service DataAccessLayer(server)[Data Access Layer] in SecurityLayers
service DatabaseSystem(database)[Database System] in SecurityLayers
service DataStorage(disk)[Encrypted Data Storage] in SecurityLayers
FrontendLayer:R -- L:APILayer
APILayer:R -- L:ServiceLayer
ServiceLayer:R -- L:DataAccessLayer
DataAccessLayer:R -- L:DatabaseSystem
DatabaseSystem:B -- T:DataStorage
```
```mermaid
flowchart TD
subgraph F[Frontend Layer]
Frontend[Frontend Components]
end
subgraph A[API Layer]
APILayer[API Layer]
end
subgraph S[Service Layer]
ServiceLayer[Service Layer]
end
subgraph D[Data Access Layer]
DataAccessLayer[Data Access Layer]
end
subgraph DB[Database System]
DatabaseSystem[Database System]
DataStorage[Encrypted Data Storage]
end
Frontend -->|Secure API Calls| APILayer
APILayer -->|Authentication & Authorization| ServiceLayer
ServiceLayer -->|Data Access| DataAccessLayer
DataAccessLayer -->|Database Queries| DatabaseSystem
DatabaseSystem -->|Encrypted Data Storage| DataStorage
classDef securityLayer fill:#f96,stroke:#333,stroke-width:2px;
class Frontend,APILayer,ServiceLayer,DataAccessLayer,DatabaseSystem securityLayer;
```
## Level 2: Security Layers Explanation
### Frontend Layer
The Frontend Layer implements secure communication protocols (e.g., HTTPS) to ensure data transmitted between the client and server is encrypted. It also incorporates input validation to prevent common vulnerabilities such as XSS and CSRF attacks.
### API Layer
The API Layer enforces authentication and authorization mechanisms to control access to backend services. It validates incoming requests and ensures that only authorized users can access specific resources.
### Service Layer
The Service Layer handles business logic while ensuring that data processing adheres to security policies. It also manages session security and implements rate limiting to prevent abuse.
### Data Access Layer
The Data Access Layer is responsible for securely interacting with the database. It uses parameterized queries to prevent SQL injection attacks and ensures that data access is logged for auditing purposes.
### Database System
The Database System employs encryption at rest and in transit to protect sensitive data. It also implements access controls to restrict database access based on user roles.
Data is regularly backed up, and recovery procedures are in place to ensure data integrity in case of failures.
### Encrypted Data Storage
All sensitive data stored in the system is encrypted using industry-standard encryption algorithms. This ensures that even if data storage is compromised, the data remains protected and inaccessible to unauthorized users.

35
architecture/08_concepts/08_ui_design.md Normal file
View File

@@ -0,0 +1,35 @@
# User Interface Design Principles
<!-- CalMiner aims to provide a comprehensive platform for mining project scenario analysis, enabling stakeholders to make informed decisions based on data-driven insights. -->
A user-friendly and intuitive user interface (UI) is crucial for the success of the Calminer system. The UI design principles outlined below ensure that users can effectively interact with the system, access necessary features, and derive maximum value from the platform.
## Key Design Principles
1. **Clarity**: The UI presents information clearly and concisely, minimizing cognitive load and helping users understand the system's functionality.
2. **Consistency**: The UI maintains a consistent look and feel across all components, ensuring users can easily navigate and interact with the system.
3. **Customizability**: The UI allows customization for individual settings and preferences, enabling a true multi-tenancy look and feel.
4. **Responsiveness**: The UI adapts to different screen sizes and devices, providing an optimal experience for all users.
5. **Simplicity**: The design prioritizes simplicity, presenting information clearly and avoiding unnecessary complexity.
6. **Feedback**: The UI provides timely feedback to user actions, ensuring users are informed of the results of their interactions.
## Concepts
To facilitate the implementation of these design principles, the following concepts are employed in the UI design:
- **Modular Design**: The UI is structured into modular components, allowing for easy maintenance, updates, and scalability.
- **Intuitive Navigation**: Clear navigation paths and menus are provided to help users find features and information quickly.
- **Visual Hierarchy**: Important elements are emphasized through size, color, and placement to guide user attention.
- **Accessibility**: The UI is designed to be accessible to users with disabilities, following best practices for inclusive design.
- **User-Centered Design**: The design process involves user feedback and testing to ensure the UI meets the needs and expectations of its target audience.
- **Interactive Elements**: Buttons, forms, and other interactive elements are designed to be easily identifiable and usable.
- **Data Visualization**: Charts, graphs, and other visual tools are used to present complex data in an understandable format.
## Implementation Considerations
When implementing the UI design principles and concepts, the following considerations should be taken into account:
- **Performance**: The UI should load quickly and respond promptly to user interactions to ensure a smooth user experience.
- **Cross-Browser Compatibility**: The UI should function consistently across different web browsers and platforms.
- **Localization**: The UI should support multiple languages and regional settings to accommodate a diverse user base.
- **Security**: The UI should incorporate security best practices to protect user data and prevent unauthorized access.

58
architecture/10_quality_requirements.md Normal file
View File

@@ -0,0 +1,58 @@
# Quality Requirements
<!--
This section contains all relevant quality requirements.
The most important of these requirements have already been described in section 1.2. (quality goals), therefore they should only be referenced here. In this section 10 you should also capture quality requirements with lesser importance, which will not create high risks when they are not fully achieved (but might be _nice-to-have_).
_Motivation:_ Since quality requirements will have a lot of influence on architectural decisions you should know what qualities are really important for your stakeholders, in a specific and measurable way.
-->
## Quality Requirements Overview
The Calminer system is designed to meet a comprehensive set of quality requirements that ensure its effectiveness, reliability, and user satisfaction.
### Effectiveness
> The system must support the creation and analysis of multiple project scenarios to assess risks and opportunities effectively.
CalMiner is based on efficient data processing algorithms and leverages PostgreSQL's capabilities to handle large datasets.
### Reliability
> The system must provide stakeholders with access to real-time data and analytics to inform their decisions.
CalMiner achieves this by utilizing a combination of data streaming and in-memory processing techniques to deliver insights with minimal latency.
### Usability
> The platform must feature an intuitive interface that minimizes the learning curve for new users.
The UI design principles outlined in the [UI Design Documentation](08_03_ui_design.md) guide the development of a user-friendly interface that adheres to best practices in usability and accessibility.
### Security
> The system must implement robust security measures, including data encryption and access controls, to protect sensitive information.
CalMiner employs industry-standard encryption protocols and access control mechanisms to safeguard data at rest and in transit.
### Scalability
> The architecture must support scaling to accommodate increasing amounts of data and users without performance degradation.
CalMiner is designed with a modular architecture that allows for horizontal and vertical scaling. Adjustments to some layers of the architecture may be necessary to fully realize scalability.
### Maintainability
> The system must be designed for easy updates and maintenance, minimizing downtime during such activities.
CalMiner achieves this by following best practices in software development, including modular design, comprehensive documentation, and automated testing.
## Detailed Quality Requirements
In addition to the overarching quality requirements outlined above, we also want to capture additional quality requirements that contribute to the overall performance and user experience of the Calminer system. These include:
- **Performance**: The system should be able to process and analyze data in real-time, providing users with immediate feedback and insights.
- **Interoperability**: CalMiner must be able to integrate with other tools and platforms commonly used in the industry, facilitating seamless data exchange and collaboration.
- **Flexibility**: The architecture should allow for easy adaptation to changing requirements and the incorporation of new technologies as they emerge.

69
architecture/11_technical_risks.md Normal file
View File

@@ -0,0 +1,69 @@
# Risks and Technical Debts
<!--
A list of identified technical risks or technical debts, ordered by priority
-->
## Identified Risks
### Data Integration Challenges
> [!WARNING]
> Integrating diverse data sources (geological, financial, operational) may lead to inconsistencies and data quality issues.
Implement robust ETL processes and data validation mechanisms to ensure data integrity.
### Security Vulnerabilities
> [!WARNING]
> Potential security vulnerabilities could expose sensitive data to unauthorized access.
Conduct regular security audits, implement strong encryption, and enforce access controls.
### Scalability Limitations
> [!NOTE]
> The system may face performance degradation as data volume and user load increase.
Design the architecture for horizontal scaling and conduct regular performance testing.
### Regulatory Compliance Risks
> [!NOTE]
> Non-compliance with data privacy regulations (e.g., GDPR, CCPA) could result in legal penalties and reputational damage.
Stay updated with regulatory changes, implement compliance monitoring, and conduct regular audits.
## Technical Debts
### Documentation Gaps
> [!NOTE]
> Incomplete documentation can lead to misunderstandings and increased onboarding time for new team members.
Establish a documentation review process and allocate time for updates in each development sprint.
### Testing Coverage Gaps
> [!NOTE]
> Insufficient automated tests may lead to undetected bugs and regressions.
Expand the test suite to cover critical components and implement continuous integration practices.
### UI/UX Improvements
> [!TIP]
> The user interface may not fully meet user expectations, affecting usability and satisfaction.
Gather user feedback and plan iterative UI/UX enhancements in future releases.
### Performance Optimization
> [!TIP]
> Performance bottlenecks may arise as the system scales, impacting user experience.
Conduct regular performance profiling and optimization efforts to ensure smooth operation under load.
## Risk and Debt Management
Regularly review and update the risk and technical debt register during sprint retrospectives and planning sessions. Prioritize mitigation and resolution efforts based on impact and urgency, ensuring that the architecture remains robust and adaptable to evolving requirements.

18
architecture/12_glossary.md Normal file
View File

@@ -0,0 +1,18 @@
# Glossary
## Terms
| Term | Definition |
| ---- | ------------------------------------------------------------------------------------------------ |
| API | Application Programming Interface, a set of rules and tools for building software applications. |
| ETL | Extract, Transform, Load; a process for moving and transforming data from one system to another. |
| UI | User Interface, the space where interactions between humans and machines occur. |
| UX | User Experience, the overall experience a user has when interacting with a product or service. |
## Project-Specific Terms
| Term | Definition |
| --------------- | ------------------------------------------------------------------------------ |
| CalMiner | The name of the mining data analysis system being developed. |
| Mining Scenario | A specific set of conditions and parameters used to analyze mining projects. |
| Multi-Tenancy | An architecture where a single instance of software serves multiple customers. |

20
architecture/about-arc42.md Normal file
View File

@@ -0,0 +1,20 @@
# About arc42
arc42, the template for documentation of software and system architecture.
Template Version: Latest
Created, maintained and © by Dr. Peter Hruschka, Dr. Gernot Starke and contributors.
See [https://arc42.org](https://arc42.org).
## What is arc42?
arc42 is a template for documenting software architectures. It provides a comprehensive structure for capturing all aspects of a system's architecture in a consistent and understandable way.
## Why use arc42?
- Provides a proven structure for architecture documentation
- Helps communicate architecture decisions to stakeholders
- Ensures completeness and consistency
- Is free and open source