(frontend_guide)=
# Frontend Guide

[NexusLIMS-CDCS](https://github.com/datasophos/NexusLIMS-CDCS) is the frontend for NexusLIMS. 
It is a heavily customized version of the [Configurable Data Curation System](https://cdcs.nist.gov/)
application developed by the Information Technology Lab at NIST.
It provides a web-based platform for searching, visualizing, and managing the experimental records
generated by the NexusLIMS backend.

```{note}
NexusLIMS-CDCS is maintained by [Datasophos](https://datasophos.co) and is
**not affiliated with NIST**. For more information, see the
[repository](https://github.com/datasophos/NexusLIMS-CDCS).
```

## About This Guide

This guide covers:
- **Deploying** NexusLIMS-CDCS for development or production
- **Configuring** environment variables and settings
- **Administering** backups, XSLT stylesheets, and user management
- **Troubleshooting** common issues

**For backend documentation** (record building, metadata extraction, harvesters), see the [User Guide](user_guide.md) and [Developer Guide](dev_guide.md).

---

## Key Features

NexusLIMS-CDCS provides:

- **Structured Data Capture** - XML schema-based templates for consistent metadata
- **Powerful Search** - Full-text and field-specific search across all records
- **Data Visualization** - XSLT-based rendering of XML records to rich HTML
- **RESTful API** - Programmatic access for automation and integration
- **User Authentication** - Role-based access control and permissions
- **Instrument Data Integration** - Links to raw experimental files via file server

---

## Architecture

NexusLIMS-CDCS uses a containerized architecture with four main services:

```{mermaid}
%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#e3f2fd', 'primaryTextColor': '#000', 'primaryBorderColor': '#1976d2', 'lineColor': '#1976d2'}}}%%
flowchart LR
    subgraph External
        Browser([Browser])
        NexusLIMS([NexusLIMS Backend])
    end

    subgraph Docker["Docker Compose Stack"]
        Caddy[Caddy<br/>Reverse Proxy<br/>File Server]
        Django[Django App<br/>Gunicorn/Runserver]
        Postgres[(PostgreSQL)]
        Redis[(Redis)]
    end

    Browser -->|HTTPS :443| Caddy
    Caddy -->|Proxy :8000| Django
    Django -->|:5432| Postgres
    Django -->|:6379| Redis
    NexusLIMS -->|REST API| Django

    classDef external fill:#fff3e0,stroke:#f57c00,stroke-width:2px
    classDef service fill:#e1f5ff,stroke:#1976d2,stroke-width:2px

    class Browser,NexusLIMS external
    class Caddy,Django,Postgres,Redis service
```

**Services:**

| Service | Purpose |
|---------|---------|
| **Caddy** | HTTPS reverse proxy with automatic certificates, serves instrument data and preview files |
| **Django (CDCS)** | Main application - handles search, record management, user auth |
| **PostgreSQL** | Primary database for records, users, templates, XSLT |
| **Redis** | Cache and session storage |

---

## Quick Start

````{grid} 2
:gutter: 3

```{grid-item-card} Screenshot Gallery
:link: frontend_guide/gallery
:link-type: doc

Visual tour of the CDCS web interface and its features.
```

```{grid-item-card} Development Setup
:link: frontend_guide/development
:link-type: doc

Set up a local development environment with hot-reload and test data.
```

```{grid-item-card} Production Deployment
:link: frontend_guide/production
:link-type: doc

Deploy to production with HTTPS, backups, and security hardening.
```

```{grid-item-card} Configuration
:link: frontend_guide/configuration
:link-type: doc

Environment variables, XSLT URLs, file paths, and optional integrations.
```

```{grid-item-card} Administration
:link: frontend_guide/administration
:link-type: doc

Backups, XSLT updates, schema management, and monitoring.
```

````

---

## Technical Stack

- **Backend Framework**: Django (Python)
- **Database**: PostgreSQL
- **Cache**: Redis
- **Web Server**: Caddy (with automatic HTTPS via Let's Encrypt)
- **Container Platform**: Docker and Docker Compose
- **Package Management**: UV (with pyproject.toml and lockfile for reproducible builds)
- **Base System**: NIST MDCS (Materials Data Curation System)

---

## Integration with NexusLIMS

NexusLIMS-CDCS works alongside the [NexusLIMS backend](https://github.com/datasophos/NexusLIMS):

1. **NexusLIMS Backend** harvests sessions from NEMO and extracts metadata from microscopy files
2. **NexusLIMS Backend** builds XML records and uploads them to CDCS via REST API
3. **CDCS Web Interface** stores, indexes, and displays the records
4. **Users** search, browse, and export records through the CDCS web interface

```{seealso}
- {ref}`Configuration variables <configuration>` for connecting NexusLIMS to CDCS (`NX_CDCS_URL`, `NX_CDCS_TOKEN`)
- The [CDCS Integration](reference/api.md) section in the API reference
```

---

## Additional Resources

```{toctree}
:maxdepth: 1

frontend_guide/gallery
frontend_guide/overview
frontend_guide/development
frontend_guide/production
frontend_guide/local-test-deployment
frontend_guide/configuration
frontend_guide/customization
frontend_guide/administration
frontend_guide/troubleshooting
```

---

## Getting Help

- **Repository**: [https://github.com/datasophos/NexusLIMS-CDCS](https://github.com/datasophos/NexusLIMS-CDCS)
- **Issues**: [https://github.com/datasophos/NexusLIMS-CDCS/issues](https://github.com/datasophos/NexusLIMS-CDCS/issues)
- **Professional Support**: [Datasophos](https://datasophos.co) offers deployment, customization, and training services