zwitschi
04d7f202b6
Some checks failed
CI / test (pull_request) Failing after 1m8s
- Introduced a new document outlining UI structure, reusable template components, CSS variable conventions, and per-page data/actions for the CalMiner application. - Removed outdated idempotency audit and logging audit documents as they are no longer relevant. - Updated quickstart guide to streamline developer setup instructions and link to relevant documentation. - Created a roadmap document detailing scenario enhancements and data management strategies. - Deleted the seed data plan document to consolidate information into the setup process. - Refactored setup_database.py for improved logging and error handling during database setup and migration processes.
105 lines
4.9 KiB
Markdown
105 lines
4.9 KiB
Markdown
# CalMiner
|
|
|
|
A web application to plan mining projects and estimate costs, returns and profitability.
|
|
|
|
Focuses on ore mining operations and covering parameters such as capital and operational expenditures, resource consumption, production output, and Monte Carlo simulations for risk analysis.
|
|
|
|
The system is designed to help mining companies make informed decisions by simulating various scenarios and analyzing potential outcomes based on stochastic variables.
|
|
|
|
## Current Features
|
|
|
|
> [!TIP]
|
|
> TODO: Update this section to reflect the current feature set.
|
|
|
|
| Feature | Category | Description | Status |
|
|
| ---------------------- | ----------- | ------------------------------------------------------------------------------------ | ----------- |
|
|
| Scenario Management | Core | Manage multiple mining scenarios with independent parameter sets and outputs. | Done |
|
|
| Parameter Definition | Core | Define and manage various parameters for each scenario. | Done |
|
|
| Cost Tracking | Financial | Capture and analyze capital and operational expenditures. | Done |
|
|
| Consumption Tracking | Operational | Record resource consumption tied to scenarios. | Done |
|
|
| Production Output | Operational | Store and analyze production metrics such as tonnage, recovery, and revenue drivers. | Done |
|
|
| Equipment Management | Operational | Manage equipment inventories and specifications for each scenario. | Done |
|
|
| Maintenance Logging | Operational | Log maintenance events and costs associated with equipment. | Started |
|
|
| Reporting Dashboard | Analytics | View aggregated statistics and visualizations for scenario outputs. | In Progress |
|
|
| Monte Carlo Simulation | Analytics | Run stochastic simulations to assess risk and variability in outcomes. | Started |
|
|
| Application Settings | Core | Manage global application settings such as themes and currency options. | Done |
|
|
|
|
## Key UI/UX Features
|
|
|
|
- **Unified UI Shell**: Server-rendered templates extend a shared base layout with a persistent left sidebar linking scenarios, parameters, costs, consumption, production, equipment, maintenance, simulations, and reporting views.
|
|
- **Modular Frontend Scripts**: Page-specific interactions in `static/js/` modules, keeping templates lean while enabling browser caching and reuse.
|
|
|
|
## Planned Features
|
|
|
|
See [Roadmap](docs/roadmap.md) for details on planned features and enhancements.
|
|
|
|
## Documentation & quickstart
|
|
|
|
This repository contains detailed developer and architecture documentation in the `docs/` folder.
|
|
|
|
### Settings overview
|
|
|
|
The Settings page (`/ui/settings`) lets administrators adjust global theme colors stored in the `application_setting` table. Changes are instantly applied across the UI. Environment variables prefixed with `CALMINER_THEME_` (for example, `CALMINER_THEME_COLOR_PRIMARY`) automatically override individual CSS variables and render as read-only in the form, ensuring deployment-time overrides take precedence while remaining visible to operators.
|
|
|
|
[Quickstart](docs/quickstart.md) contains developer quickstart, migrations, testing and current status.
|
|
|
|
Key architecture documents: see [architecture](docs/architecture/README.md) for the arc42-based architecture documentation.
|
|
|
|
For contributors: the `routes/`, `models/` and `services/` folders contain the primary application code. Tests and E2E specs are in `tests/`.
|
|
|
|
## Run with Docker
|
|
|
|
The repository ships with a multi-stage `Dockerfile` that produces a slim runtime image.
|
|
|
|
### Build container
|
|
|
|
```bash
|
|
docker build -t calminer .
|
|
```
|
|
|
|
### Push to registry
|
|
|
|
To push the image to a registry, tag it appropriately and push:
|
|
|
|
```bash
|
|
docker tag calminer your-registry/calminer:latest
|
|
docker push your-registry/calminer:latest
|
|
```
|
|
|
|
### Run container
|
|
|
|
To run the container, ensure PostgreSQL is available and set environment variables:
|
|
|
|
```bash
|
|
docker run -p 8000:8000 \
|
|
-e DATABASE_HOST=your-postgres-host \
|
|
-e DATABASE_PORT=5432 \
|
|
-e DATABASE_USER=calminer \
|
|
-e DATABASE_PASSWORD=your-password \
|
|
-e DATABASE_NAME=calminer_db \
|
|
calminer
|
|
```
|
|
|
|
## Development with Docker Compose
|
|
|
|
For local development, use `docker-compose.yml` which includes the app and PostgreSQL services.
|
|
|
|
```bash
|
|
# Start services
|
|
docker-compose up
|
|
|
|
# Or run in background
|
|
docker-compose up -d
|
|
|
|
# Stop services
|
|
docker-compose down
|
|
```
|
|
|
|
The app will be available at `http://localhost:8000`, PostgreSQL at `localhost:5432`.
|
|
|
|
## CI/CD
|
|
|
|
CalMiner uses Gitea Actions workflows stored in `.gitea/workflows/`:
|
|
|
|
- `ci.yml`: Runs on push and PR to main/develop branches. Sets up Python, installs dependencies, runs tests with coverage, and builds the Docker image.
|