allucanget/calminer
2
0
Fork 0
Code Pull Requests Actions Packages Releases Activity

Add UI and styling documentation; remove idempotency and logging audits
Some checks failed
CI / test (pull_request) Failing after 1m8s
Details

Browse Source 
- 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.
This commit is contained in:
zwitschi
2025-10-29 13:20:44 +01:00
parent 1f58de448c
commit 04d7f202b6
19 changed files with 609 additions and 752 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
README.md
View File

@@ -6,24 +6,32 @@ Focuses on ore mining operations and covering parameters such as capital and ope
The system is designed to help mining companies make informed decisions by simulating various scenarios and analyzing potential outcomes based on stochastic variables.
A range of features are implemented to support these functionalities.
## Current Features
## 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
- **Scenario Management**: Manage multiple mining scenarios with independent parameter sets and outputs.
- **Process Parameters**: Define and persist process inputs via FastAPI endpoints and template-driven forms.
- **Cost Tracking**: Capture capital (`capex`) and operational (`opex`) expenditures per scenario.
- **Consumption Tracking**: Record resource consumption (chemicals, fuel, water, scrap) tied to scenarios.
- **Production Output**: Store production metrics such as tonnage, recovery, and revenue drivers.
- **Equipment Management**: Register scenario-specific equipment inventories.
- **Maintenance Logging**: Log maintenance events against equipment with dates and costs.
- **Reporting Dashboard**: Surface aggregated statistics for simulation outputs with an interactive Chart.js dashboard.
- **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.
- **Operations Overview Dashboard**: The root route (`/`) surfaces cross-scenario KPIs, charts, and maintenance reminders with a one-click refresh backed by aggregated loaders.
- **Theming Tokens**: Shared CSS variables in `static/css/main.css` centralize the UI color palette for consistent styling and rapid theme tweaks.
- **Settings Center**: The Settings landing page exposes visual theme controls and links to currency administration, backed by persisted application settings and environment overrides.
- **Modular Frontend Scripts**: Page-specific interactions in `static/js/` modules, keeping templates lean while enabling browser caching and reuse.
- **Monte Carlo Simulation (in progress)**: Services and routes are scaffolded for future stochastic analysis.
## Planned Features
See [Roadmap](docs/roadmap.md) for details on planned features and enhancements.
## Documentation & quickstart
@@ -45,59 +53,52 @@ The repository ships with a multi-stage `Dockerfile` that produces a slim runtim
### Build container
```powershell
# Build the image locally
docker build -t calminer:latest .
```bash
docker build -t calminer .
```
### Push to registry
```powershell
# Tag and push the image to your registry
docker login your-registry.com -u your-username -p your-password
docker tag calminer:latest your-registry.com/your-namespace/calminer:latest
docker push your-registry.com/your-namespace/calminer:latest
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
Expose FastAPI on <http://localhost:8000> with database configuration via granular environment variables:
To run the container, ensure PostgreSQL is available and set environment variables:
```powershell
# Provide database configuration via granular environment variables
docker run --rm -p 8000:8000 ^
-e DATABASE_DRIVER="postgresql" ^
-e DATABASE_HOST="db.host" ^
-e DATABASE_PORT="5432" ^
-e DATABASE_USER="calminer" ^
-e DATABASE_PASSWORD="s3cret" ^
-e DATABASE_NAME="calminer" ^
-e DATABASE_SCHEMA="public" ^
calminer:latest
```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
```
### Orchestrated Deployment
## Development with Docker Compose
Use `docker compose` or an orchestrator of your choice to co-locate PostgreSQL/Redis/Traefik alongside the app when needed. The image expects migrations to be applied before startup.
For local development, use `docker-compose.yml` which includes the app and PostgreSQL services.
### Production docker-compose workflow
```bash
# Start services
docker-compose up
`docker-compose.prod.yml` covers the API plus optional Traefik (`reverse-proxy` profile) and on-host Postgres (`local-db` profile). Commands, health checks, and environment variables are documented in [docs/quickstart.md](docs/quickstart.md#compose-driven-production-stack) and expanded in [docs/architecture/07_deployment_view.md](docs/architecture/07_deployment_view.md).
# Or run in background
docker-compose up -d
### Development docker-compose workflow
# Stop services
docker-compose down
```
`docker-compose.dev.yml` runs FastAPI (with reload) and Postgres in a single stack. See [docs/quickstart.md](docs/quickstart.md#compose-driven-development-stack) for lifecycle commands and troubleshooting, plus the architecture chapter ([docs/architecture/15_development_setup.md](docs/architecture/15_development_setup.md)) for deeper context.
The app will be available at `http://localhost:8000`, PostgreSQL at `localhost:5432`.
### Test docker-compose workflow
`docker-compose.test.yml` mirrors the CI pipeline: it provisions Postgres, runs the database bootstrap script, and executes pytest. Usage examples live in [docs/quickstart.md](docs/quickstart.md#compose-driven-test-stack).
## CI/CD expectations
## CI/CD
CalMiner uses Gitea Actions workflows stored in `.gitea/workflows/`:
- `test.yml` runs style/unit/e2e suites on every push with cached Python dependencies.
- `build-and-push.yml` builds the Docker image, reuses cached layers, and pushes to the configured registry.
- `deploy.yml` pulls the pushed image on the target host and restarts the container.
Pipelines assume the following secrets are provisioned in the Gitea instance: `REGISTRY_USERNAME`, `REGISTRY_PASSWORD`, `REGISTRY_URL`, `SSH_HOST`, `SSH_USERNAME`, and `SSH_PRIVATE_KEY`.
- `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.