CyVerse Portal Development

Development guidelines and tooling for working on the CyVerse portal2 project.

Code Guidelines

Follow these principles when writing code for the portal:

1. **Keep code succinct** - Write clear, concise code without unnecessary verbosity

2. **Add validation** - Validate input on both backend and frontend

3. **Don't repeat yourself (DRY)** - Extract common patterns into reusable functions

4. **Avoid multiple inheritance** - Keep class hierarchies simple

5. **Prefer composition over inheritance** - For new first-party types, use composition patterns

6. **Use table-driven tests** - Rather than many small, similar test functions

7. **Add doc comments** - Document all publicly available methods and functions

8. **Document succinctly but thoroughly** - Explain what, why, and edge cases

9. **Use type hinting in Python** - Add type annotations to function signatures

10. **Treat warnings as errors** - Unless fixing would cause difficult-to-fix breakages

Tooling

Project Structure

**portal-conductor**: API backend for the portal, usually available at `../portal-conductor/`. Provides the API layer consumed by the portal frontend.

Common Commands

Development Server

```bash

npm run dev

```

Starts the portal locally in development mode.

Test Portal Conductor Connection

```bash

curl -k https://portal-conductor/

```

Verifies that the portal-conductor API is available locally.

Instructions for AI Agent

When working on the CyVerse portal2 codebase:

1. **Before making changes**, read existing code in the relevant files to understand current patterns and architecture

2. **Validate input** - Add validation logic both in API routes (backend) and form components (frontend)

3. **Extract repetition** - If you see similar code blocks, refactor into a shared utility function

4. **Document changes** - Add docstrings to new functions and JSDoc comments to new TypeScript functions

5. **Type everything** - Use TypeScript types for frontend code and Python type hints for backend code

6. **Write table-driven tests** - When adding test coverage, use parameterized tests with a data table rather than many individual test functions

7. **Check for portal-conductor** - If the portal needs backend API changes, check if `../portal-conductor/` exists and coordinate changes

8. **Use uv commands** - For Python dependency management and script execution, use `uv` commands (e.g., `uv pip install`, `uv run`)

9. **Prefer podman** - If building container images, check if `podman` is available and use it instead of `docker`

Example Workflows

Adding a new API endpoint in portal-conductor

1. Navigate to `../portal-conductor/`

2. Add route handler with input validation

3. Add type hints to function signature

4. Write doc comment explaining endpoint purpose

5. Add table-driven tests covering happy path and edge cases

Adding a new form in the portal

1. Read existing form components to match patterns

2. Create form component with client-side validation

3. Add API route handler with server-side validation

4. Document the component with JSDoc

5. Test both validation layers (client and server)