> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbusbci.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nimbus Development Workflow

> Build production BCI applications with Nimbus using practical project structure, testing, debugging, and deployment guidance.

# Development Guide

This guide covers project organization and production workflow. It does not repeat SDK installation or full examples; use the linked pages for those details.

<Note>
  * Python setup: [Python SDK Installation](/python-sdk/installation)
  * Julia setup: [Julia SDK Quickstart](/julia-sdk/quickstart)
  * Recipes: [Basic Examples](/examples/basic-examples) and [Advanced Applications](/examples/advanced-applications)
</Note>

## Recommended Project Structure

Keep acquisition, preprocessing, inference, and application logic separate. That makes it easier to test each stage and swap SDKs or models later.

```text theme={null}
my-bci-project/
  src/
    acquisition/       # LSL, BrainFlow, hardware adapters
    preprocessing/     # filtering, artifact handling, feature extraction
    models/            # training, loading, normalization params
    inference/         # batch and streaming inference
    app/               # UI, control, feedback, safety policy
  data/
    raw/
    processed/
    calibration/
  tests/
  notebooks/
  README.md
```

## Development Workflow

1. **Define the BCI paradigm**: motor imagery, P300, SSVEP, or another task.
2. **Lock preprocessing**: feature type, sampling rate, channels, temporal window, normalization.
3. **Train a baseline**: start with `NimbusLDA`, then compare alternatives only if the baseline fails.
4. **Evaluate offline**: use cross-validation and held-out sessions before streaming.
5. **Add streaming**: process feature chunks and aggregate trial decisions.
6. **Add safety policy**: reject low confidence trials and log uncertainty.
7. **Deploy with monitoring**: track latency, confidence, rejection rate, and drift.

## Data Contracts

Document these invariants in your project:

| Field                | Why It Matters                                                                                |
| -------------------- | --------------------------------------------------------------------------------------------- |
| Sampling rate        | Required for reproducible windows and chunk sizes.                                            |
| Feature type         | Models trained on CSP should not receive ERP features.                                        |
| Feature count        | Must match the model and metadata.                                                            |
| Label encoding       | Python workflows can use sklearn-style labels; Julia examples typically use 1-indexed labels. |
| Normalization params | Must be estimated on training data and reused for deployment.                                 |

## Model Lifecycle

Treat a deployed model as more than weights. Save:

* model object or model identifier
* SDK version
* feature extraction settings
* normalization parameters
* class labels and label mapping
* training session metadata
* validation metrics

Example metadata:

```json theme={null}
{
  "model": "NimbusLDA",
  "sdk": "nimbus-bci",
  "feature_type": "csp",
  "sampling_rate": 250,
  "n_features": 8,
  "normalization": "zscore",
  "trained_on": "2026-04-25"
}
```

## Testing Strategy

Prioritize small tests around contracts and failure modes:

* Preprocessing output has expected shape and finite values.
* Labels match the number of trials.
* Normalization params are reused, not recomputed on test data.
* Model rejects incompatible feature dimensions.
* Streaming chunks match `chunk_size`.
* Low-confidence predictions trigger the expected safety path.

For numerical tests, avoid hardcoding exact posteriors unless the model is fully deterministic. Prefer shape, range, monotonicity, and threshold checks.

## Debugging Checklist

When accuracy or confidence is poor:

1. Confirm data shape and label encoding.
2. Check for NaN, Inf, constant features, or raw EEG accidentally passed as features.
3. Verify the preprocessing band and time window match the paradigm.
4. Reuse training normalization parameters on test data.
5. Compare against `NimbusLDA` as a baseline.
6. Inspect confidence and posterior entropy, not only accuracy.
7. Run preprocessing diagnostics before tuning model hyperparameters.

## Performance Guidance

* Warm up streaming inference before a live session.
* Preallocate buffers in real-time loops.
* Keep filtering and feature extraction outside hot model code when possible.
* Prefer batch inference for offline evaluation.
* Log per-stage latency: acquisition, preprocessing, inference, and application action.

## Production Guardrails

Production BCI systems should include:

* confidence thresholds by action risk
* trial rejection and retry flows
* session-level health monitoring
* model/version audit logs
* fallback behavior when the stream drops
* clear separation between prediction and command execution

See [Error Handling](/inference-configuration/error-handling) for a focused checklist.

## Next Read

<CardGroup cols={2}>
  <Card title="External Preprocessing Integration" icon="link" href="/development/preprocessing-integration">
    Export/import handoff from MNE, EEGLAB, OpenViBE, or MATLAB.
  </Card>

  <Card title="Feature Normalization" icon="arrows-up-down" href="/inference-configuration/feature-normalization">
    Cross-session scaling strategy.
  </Card>

  <Card title="Streaming Configuration" icon="activity" href="/inference-configuration/streaming-inference">
    Chunking, aggregation, and quality gates.
  </Card>

  <Card title="Model Specification" icon="brain" href="/model-specification">
    Choose the right model family.
  </Card>
</CardGroup>