# Tethys Research Repository Backend System

Welcome to the Tethys Research Repository Backend System! This is the backend component responsible for managing datasets, users, and the core functionality of the Tethys Data Research Repository.

## Table of Contents

-   [Getting Started](#getting-started)
    -   [Prerequisites](#prerequisites)
    -   [Installation](#installation)
-   [Usage](#usage)
-   [Configuration](#configuration)
-   [Database](#database)
-   [API Documentation](#api-documentation)
-   [Commands](#commands)
-   [Documentation](#documentation)
-   [Contributing](#contributing)
-   [License](#license)

## Getting Started

### Prerequisites

Before you begin, ensure you have met the following requirements:

-   Node.js and npm installed on your development machine.
-   A running PostgreSQL database instance.
-   AdonisJS CLI globally installed.

### Installation

1. Clone this repository:

    ```bash
    git clone git clone https://gitea.geologie.ac.at/geolba/tethys.backend.git
    cd tethys-backend
    ```

2. Install dependencies:

    ```bash
    npm install
    ```

3. Configure environment variables (see [Configuration](#configuration))

4. Run database migrations:

    ```bash
    node ace migration:run
    ```

5. Start the development server:

    ```bash
    npm run dev
    ```

## Usage

The Tethys Backend provides RESTful APIs for managing research datasets, user authentication, DOI registration, and search functionality.

## Configuration

Copy the `.env.example` file to `.env` and configure the following variables:

### Database Configuration
```bash
DB_CONNECTION=pg
DB_HOST=localhost
DB_PORT=5432
DB_USER=your_username
DB_PASSWORD=your_password
DB_DATABASE=tethys_db
```

### DataCite Configuration
```bash
# DataCite Credentials
DATACITE_USERNAME=your_datacite_username
DATACITE_PASSWORD=your_datacite_password
DATACITE_PREFIX=10.21388

# Environment-specific API endpoints
DATACITE_API_URL=https://api.test.datacite.org      # Test environment
DATACITE_SERVICE_URL=https://mds.test.datacite.org  # Test MDS

# For production:
# DATACITE_API_URL=https://api.datacite.org
# DATACITE_SERVICE_URL=https://mds.datacite.org
```

### OpenSearch Configuration
```bash
OPENSEARCH_HOST=localhost:9200
```

### Application Configuration
```bash
BASE_DOMAIN=tethys.at
APP_KEY=your_app_key
```

## Database

The system uses PostgreSQL with Lucid ORM. Key models include:

- **Dataset**: Research dataset metadata
- **DatasetIdentifier**: DOI and other identifiers for datasets
- **User**: User management and authentication
- **XmlCache**: Cached XML metadata

Run migrations and seeders:

```bash
# Run migrations
node ace migration:run

# Run seeders (if available)
node ace db:seed
```

## API Documentation

API endpoints are available for:

- Dataset management (`/api/datasets`)
- User authentication (`/api/auth`)
- DOI registration (`/api/doi`)
- Search functionality (`/api/search`)

*Detailed API documentation can be found in the `/docs/api` directory.*

## Commands

The system includes several Ace commands for maintenance and data management:

### Dataset Indexing
```bash
# Index all published datasets to OpenSearch
node ace index:datasets

# Index a specific dataset
node ace index:datasets --publish_id 123
```

### DataCite DOI Management
```bash
# Update DataCite records for modified datasets
node ace update:datacite

# Show detailed statistics for datasets needing updates
node ace update:datacite --stats

# Preview what would be updated (dry run)
node ace update:datacite --dry-run

# Force update all DOI records
node ace update:datacite --force

# Update a specific dataset
node ace update:datacite --publish_id 123
```

*For detailed command documentation, see the [Commands Documentation](docs/commands/)*

## Documentation

Comprehensive documentation is available in the `/docs` directory:

- **[Commands Documentation](docs/commands/)** - Detailed guides for Ace commands
  - [DataCite Update Command](docs/commands/update-datacite.md) - DOI synchronization and management
  - [Dataset Indexing Command](docs/commands/index-datasets.md) - Search index management
- **[API Documentation](docs/api/)** - REST API endpoints and usage
- **[Deployment Guide](docs/deployment/)** - Production deployment instructions
- **[Configuration Guide](docs/configuration/)** - Environment setup and configuration options

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Guidelines

- Follow the existing code style and conventions
- Write tests for new features
- Update documentation for any API changes
- Ensure all commands and migrations work properly

### Testing Commands

```bash
# Run tests
npm test

# Test specific commands
node ace update:datacite --dry-run --publish_id 123
node ace index:datasets --publish_id 123
```

## License

This project is licensed under the [MIT License](LICENSE).