CyVerse Portal Development

Guidelines and workflows for developing the CyVerse Discovery Environment portal and related services.

Code Quality Standards

Follow these principles when writing code for CyVerse projects:

1. **Succinctness**: Keep code concise and readable

2. **Validation**: Implement validation on both backend and frontend

3. **DRY Principle**: Don't repeat yourself unnecessarily

4. **Avoid Multiple Inheritance**: Use single inheritance patterns

5. **Composition Over Inheritance**: Prefer composition for new first-party types

6. **Testing**: Use table-driven tests instead of many small similar tests

7. **Documentation**: Add doc comments to public methods/functions; document succinctly but thoroughly

8. **Type Safety**: Use type hinting in Python code

9. **Warnings as Errors**: Treat warnings as errors unless fixing them causes difficult breakages

Tooling & Environment

Primary Tools

Project Structure

Development Workflow

Starting Local Development

1. Start the portal development server:

```bash

npm run dev

```

2. Test portal-conductor availability:

```bash

curl -k https://portal-conductor/

```

Working with Python (uv)

When working on Python components:

```bash

Install dependencies

uv pip install -r requirements.txt

Run Python scripts

uv run python script.py

Sync dependencies

uv pip sync

```

Building Container Images

When building images, prefer podman:

```bash

Build with podman (preferred)

podman build -t image-name .

If podman unavailable, fallback to docker

docker build -t image-name .

```

Testing Guidelines

Table-Driven Tests

Instead of writing many similar test cases:

```python

Good: Table-driven

test_cases = [

{"input": "a", "expected": "A"},

{"input": "b", "expected": "B"},

]

for case in test_cases:

assert transform(case["input"]) == case["expected"]

Avoid: Many similar tests

def test_a():

assert transform("a") == "A"

def test_b():

assert transform("b") == "B"

```

Documentation Standards

Public API Documentation

All publicly available methods and functions should include doc comments:

```python

def process_data(data: dict[str, any]) -> list[str]:

"""

Process incoming data and return formatted results.

Args:

data: Dictionary containing raw data to process

Returns:

List of formatted string results

Raises:

ValueError: If data is missing required keys

"""

pass

```

Type Hinting

Always use type hints in Python code:

```python

from typing import Optional

def get_user(user_id: str) -> Optional[dict[str, any]]:

"""Retrieve user by ID."""

pass

```

Validation Pattern

Implement validation on both layers:

```python

Backend validation

def create_resource(name: str, size: int):

if not name or len(name) < 3:

raise ValueError("Name must be at least 3 characters")

if size < 1:

raise ValueError("Size must be positive")

# ... create resource

```

```typescript

// Frontend validation

function validateResource(name: string, size: number): string[] {

const errors: string[] = [];

if (!name || name.length < 3) {

errors.push("Name must be at least 3 characters");

}

if (size < 1) {

errors.push("Size must be positive");

}

return errors;

}

```

Architecture Patterns

Prefer Composition

When creating new types, favor composition:

```python

Good: Composition

class DataProcessor:

def __init__(self, validator: Validator, formatter: Formatter):

self.validator = validator

self.formatter = formatter

Avoid: Multiple inheritance

class DataProcessor(Validator, Formatter):

pass

```

Troubleshooting

Portal-Conductor Connection Issues

If portal-conductor is unreachable:

1. Verify service is running

2. Check network configuration

3. Validate SSL/TLS settings (note `-k` flag for self-signed certs)

```bash

Detailed connection test

curl -v -k https://portal-conductor/health

```

Build Issues

If builds fail:

1. Check tool availability (`uv`, `podman`/`docker`)

2. Verify dependency versions

3. Review build logs for specific errors