# CDEIS Minerals - Token Management Platform

A professional Node.js-based token management and student portal application with user authentication, chat messaging, and course management capabilities.

## Features

- **Financial Core v1**: [Command centre](financial-core.html) with signed-in server demo accounts, virtual double-entry ledger, risk limits, research memory and outcome reviews. PHP/SQLite and Node/SQLite are tested; see the [implementation scope](docs/financial-core-v1.md).

- **Paper Portfolio**: [Manual demo trading](paper-trading.html) with long/short positions, planned risk limits, realized P/L and history export. See the [financial platform roadmap](docs/financial-platform-roadmap.md) for scope and the PHP/MySQL implementation path.

- **User Authentication**: Secure registration and login with session management
- **Student Portal**: Course application system with fee management
- **Token Tracker**: Real-time balance and transaction tracking
- **Chat Messaging**: Direct messaging between users
- **Admin Dashboard**: Full administrative control and analytics
- **Blockchain Integration**: Token balance management and wallet support
- **API Protection**: Built-in API rate limiting for abuse prevention
- **Monitoring Hooks**: Optional Sentry error reporting and built-in `/api/metrics`
- **Request Tracing**: Per-request correlation IDs via `X-Request-Id` for diagnostics
- **Audit Governance**: Immutable database audit events for auth and privileged commerce actions
- **API Specification**: OpenAPI document at `/api/openapi.json`
- **Knowledge Capture and RAG**: Optional React/PHP/SQLite module for approved-database-only answers from people, organizations, projects, and events

## Prerequisites

- Node.js (v22.13.0 or higher)
- npm

## Installation

1. Clone the repository:

```bash
git clone https://github.com/Fritso/cdeisMinerals.git
cd cdeisMinerals
```

1. Install dependencies:

```bash
npm install
```

On Windows, if PowerShell blocks `npm.ps1`, use `npm.cmd` in place of
`npm` for these commands (for example, `npm.cmd install`).

1. Configure environment variables:

```bash
cp .env.example .env
```

Edit `.env` with your configuration values. **Important**: Change the default admin credentials before deploying to production.

## Running the Application

Start the server:

```bash
npm start
```

The application will be available at `http://localhost:8080` (or the configured PORT).

## Testing

Run unit tests:

```bash
npm run test:unit
```

Run integration tests:

```bash
npm run integration-test
```

Run contract tests from OpenAPI:

```bash
npm run test:contract
```

Run self-contained end-to-end tests (auto starts/stops server):

```bash
npm run test:e2e
```

Run combined unit, smoke, integration, and contract tests with an automatically
managed test server and a temporary database copy:

```bash
npm test
```

`npm run test:all` runs the same complete suite.

Run the full future-readiness gate:

```bash
npm run future:check
```

## API Documentation

- OpenAPI JSON: `/api/openapi.json`
- Operational metrics (admin headers required): `/api/metrics`

## Automatic research and saved answers

CDEISLAB sends normal questions to the research service. Sourced answers are saved in SQLite with the question, citations, research time, and evidence status. Asking the same question again retrieves a fresh saved answer; Search Engine forces a new search. Search excerpts are labeled as unverified excerpts, and clarification responses are not saved as factual answers. Ordinary answers no longer receive automatic tutor exercises.

While the Node server is running, a worker checks one due topic per minute and refreshes saved research after 24 hours. The queue survives restarts and tracks up to 100 questions per user. Failed research retries with backoff and stops automatic retries after three failures; the user can ask again to retry. Calculations, code, and market risk requests bypass this cache so request-specific inputs are not reused. This is a growing source-backed memory, not model training or a guarantee that every source is correct. It researches previously requested topics rather than crawling the internet without a topic.

Set `CDEISLAB_AUTO_RESEARCH=false` to stop background refreshes. Authenticated users can inspect their topic queue at `GET /api/cdeis-lab/research/status`. The answer shows its sources, research time, saved status, and next check when scheduled. The implementation runs in the Node service; PHP-only hosting does not run this worker.

## Gold and minerals production course

Open **Gold & Minerals: From Discovery to Production** in CDEISLAB or Student Portal. Ten lessons cover finding deposits, evaluation, mining, processing, extraction, refining, balances, other minerals, environmental management and a final production study. Students can earn 30 quiz stars, saved per account, and explore a grade/recovery calculator. Sources and review notes accompany every stage.

Use `Minerals lesson: refining` in CDEISLAB for a complete authored lesson. The supplied study guide is available to signed-in learners. See [research and teaching notes](docs/minerals-course-research.md) for evidence limits, assessment rules and validation. This module requires the Node backend.

## Trading Risk Gate

The [Trading Desk](trading.html) includes a visual analysis console, validated signal cards and ten trading learning areas. Its planning tools cover position sizing, risk budgets, manual sentiment/intermarket calculations, preparation checklists and an exportable paper journal. See [workbench capabilities, sources and validation](docs/trading-workbench.md).

The PHP risk engine in `lib/trading-risk-engine.php` is the deterministic approval layer for advisory signals. It enforces 0.25% risk per trade, 1% total open risk, 1.5% daily loss, 8% drawdown, two positions, 1.5 minimum reward-to-risk, data freshness, spread, liquidity, news, correlation, duplicate-position, and slippage checks. It returns `ABSTAIN` when the calculated volume is below the broker minimum or required tick values, stops, targets, or market data are missing.

Authenticated clients can call `POST /api/trading/risk-check` with `proposal`, `account`, `instrument`, and `market` objects. This endpoint only approves or rejects a proposal; it does not place orders. MT5 execution must remain behind a separate demo/manual bridge that rechecks the returned approval, stop-loss, maximum cash loss, and expiry.

## Installable Web App

The project now includes Progressive Web App support so users can install it on Android phones, iPhones, tablets, laptops, and desktop browsers that support PWA installation.

- Manifest: `manifest.webmanifest`
- Service worker: `sw.js`
- Install bootstrap: `pwa-init.js`

If the server was already running before these files were added, restart it so the updated manifest MIME type is served correctly.

## Android APK Wrapper

Capacitor support is included for generating an Android wrapper around the existing web app without rewriting the frontend.

Useful commands:

```bash
npm run mobile:android:init
npm run mobile:android:sync
npm run mobile:android:open
npm run mobile:android:apk
CAP_SERVER_URL=https://yourdomain.com npm run mobile:android:apk:prod
```

See `mobile/README.md` for the Android workflow and production-safe APK settings for emulator and real-device builds.

## Docker

Build and run with Docker:

```bash
docker build -t cdeisminerals .
docker run --rm -p 8080:8080 cdeisminerals
```

Or use Docker Compose:

```bash
docker compose up --build
```

Run the knowledge capture and RAG frontend as well:

```bash
docker compose --profile knowledge up --build
```

Knowledge UI: `http://localhost:5173`
Knowledge API: `/knowledge-api`

See `knowledge-system/docs/INSTALLATION.md` for the PHP setup, default admin login, consent workflow, SQLite database, and hosted routes.

## Environment Variables

See `.env.example` for all available configuration options:

- `PORT`: Server port (default: 8080)
- `NODE_ENV`: Environment mode (development/production)
- `DB_TYPE`: Database type (`sqlite` for this system)
- `DATABASE_PATH`: SQLite file path
- `DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`: Legacy MySQL settings only if you intentionally switch away from SQLite
- `DEFAULT_ADMIN_EMAIL`: Default admin email address
- `DEFAULT_ADMIN_PASSWORD`: Default admin password
- `ADMIN_PASSWORD_SALT`: Server-side pepper used in password hashing
- `PASSWORD_SCRYPT_N`, `PASSWORD_SCRYPT_R`, `PASSWORD_SCRYPT_P`: Scrypt work factor controls
- `PASSWORD_SCRYPT_KEYLEN`: Derived key length for password hashes
- `PASSWORD_SCRYPT_MAXMEM`: Max memory budget for scrypt derivation
- `PASSWORD_MAX_LENGTH`: Maximum accepted password length
- `SESSION_TTL_HOURS`: Session timeout in hours
- `SESSION_COOKIE_SAMESITE`: Session cookie SameSite policy (`auto`, `lax`, `strict`, `none`)
- `SESSION_COOKIE_SECURE`: Session cookie Secure flag policy (`auto`, `true`, `false`)
- `SESSION_COOKIE_DOMAIN`: Optional cookie domain override
- `TOTAL_SUPPLY`: Total token supply
- `RATE_LIMIT_WINDOW_MS`: Rate limit window in milliseconds
- `RATE_LIMIT_MAX_REQUESTS`: Maximum requests allowed per window
- `MAX_BODY_BYTES`: Maximum accepted request payload size in bytes
- `REQUEST_TIMEOUT_MS`: Request processing timeout in milliseconds
- `HEADERS_TIMEOUT_MS`: Header read timeout in milliseconds
- `KEEP_ALIVE_TIMEOUT_MS`: Keep-alive timeout for persistent connections
- `SENTRY_DSN`: Optional Sentry DSN for error tracking
- `SENTRY_TRACES_SAMPLE_RATE`: Optional trace sampling rate
- Additional options in `.env.example`

## Data Backups

Create a SQLite backup archive:

```bash
npm run db:backup
```

The backup script is at `scripts/backup-sqlite.sh` and keeps 30 days of archives by default.

Restore from a backup archive:

```bash
npm run db:restore -- backups/sqlite/<archive>.tar.gz cdeis.sqlite
```

See `docs/disaster-recovery.md` for the full recovery runbook.

## Project Structure

```text
├── server.js                # Main Node.js server
├── index.html              # Home page
├── login.html              # User login
├── register.html           # User registration
├── user-dashboard.html     # User dashboard
├── chat.html               # Messaging interface
├── tracker.html            # Token tracker
├── admin.html              # Admin panel
├── api-client.js           # API client utilities
├── cdeis.sqlite            # SQLite database
└── images/                 # Static assets
```

## Database Schema

SQLite deployment uses these core tables:

- **users**: User account information
- **user_sessions**: Active user sessions
- **kv**: Key-value store for protocol state and admin config
- **chat_messages**: Direct message history

Note: Local Node, hosted Node, and the cPanel PHP fallback should all use SQLite by setting `DB_TYPE=sqlite`.

## API Endpoints

### Authentication

- `POST /api/register-user` - Register new user
- `POST /api/login-user` - User login
- `POST /api/logout-user` - User logout
- `GET /api/current-user` - Get current user session

### Student Portal

- `GET /api/student-portal` - Get portal information
- `POST /api/submit-student-application` - Submit course application
- `GET /api/student-applications` - List user applications

### Admin

- `GET /api/users` - List all users (admin scope)
- `PUT /api/admin-config` - Update admin configuration (admin scope)
- `GET /api/admin/audit-events` - Query immutable audit events with filters/pagination
- `GET /api/admin/audit-events/export` - Export audit events (`csv` or `ndjson`)
- `GET /api/admin/slo-summary` - View API SLO/latency/error posture summary

### Other

- `GET /api/get-protocol-state` - Get current blockchain state
- `POST /api/transfer-tokens` - Transfer tokens between wallets

## Security Considerations

- Session cookies use `HttpOnly`, `Secure`, and `SameSite` flags
- Passwords are hashed with scrypt and verified with timing-safe comparisons
- Admin credentials should be changed before production deployment
- Environment variables should be used for all sensitive configuration

## Performance Notes

- SQLite provides adequate performance for development and small-scale deployments
- Consider database migration to PostgreSQL for production with high concurrency
- Session TTL is configurable via environment variables

For PostgreSQL readiness, see `docs/postgresql-migration.md` and `migrations/postgres/001_init.sql`.

The knowledge module uses the PHP `knowledge-api.php` route and SQLite storage under `knowledge-system/`.

## License

Proprietary - CDEIS Lab

## Support

For issues or questions, please contact the development team.

## Live course classroom

Open **Student Portal ? Enter Live Classroom** (`live-classroom.html`). Approved/enrolled students receive a named desk for the portal course. Admin-approved, qualified teachers assigned through **Admin ? Teachers & Contributors ? Live Classroom Teachers** can start a named lesson period, teach through live audio/video, post board notes and exercises, accept students' waves, and return the floor to the teacher. Students can answer or demonstrate on camera or by sharing their screen after acceptance. Exercise answers and feedback are saved privately for the student and the period's teacher.

This feature runs on the Node server (`npm start`); the PHP-only backend does not implement its classroom endpoint. See [live classroom operations](docs/live-classroom.md) for access, network requirements, and tests.

## Worked calculation answers

CDEISLAB preserves the original question, formula, numbered working, checks, and final answer for its supported local calculations. The output preview typesets LaTeX and displays data and answer-sheet tables. The supplied assignment is retained as a presentation reference; unclear notation and method conventions must be stated rather than guessed. See [worked calculation guidance](docs/worked-calculations.md).

### ZIMSEC teaching hub

The student portal, library and CDEISLAB link to `teaching-hub.html`: 120 supplied PDFs across 44 subject codes, authenticated reading/downloads, teacher preparation access, page-based lesson handoff, saved study tracks and calendar export. See [teaching hub documentation](docs/zimsec-teaching-hub.md) for source handling and deployment requirements.