Nexent Backend Development Standards

This skill enforces code quality and architectural patterns for Nexent, a zero-code platform for auto-generating agents with powerful running control, data processing, and MCP tools.

Code Quality Standards

English-Only Comments and Documentation

**Rule:** All comments and docstrings MUST be written in clear, concise English.

**Examples:**

✅ **Correct:**

```python

Initialize cache for 60 seconds

self.cache_ttl = 60

```

❌ **Incorrect:**

```python

初始化缓存 60 秒 - FORBIDDEN

データキャッシュ60秒 - FORBIDDEN

```

Environment Variable Management

**Rule:** All environment variable access MUST go through `backend/consts/const.py`.

**Examples:**

✅ **Correct:**

```python

backend/consts/const.py

APPID = os.getenv("APPID", "")

TOKEN = os.getenv("TOKEN", "")

other modules

from consts.const import APPID, TOKEN

```

❌ **Incorrect:**

```python

direct calls in other modules

import os

appid = os.getenv("APPID")

token = os.environ.get("TOKEN")

```

Backend Architecture Rules

App Layer (`backend/apps/**/*.py`)

**Purpose:** HTTP boundary for the backend - parse/validate input, call services, map domain errors to HTTP.

**Responsibilities:**

**Routing and URL Design:**

**HTTP Methods:**

**Authorization:**

**Exception Mapping:**

**Example:**

```python

from http import HTTPStatus

import logging

from fastapi import APIRouter, HTTPException

from starlette.responses import JSONResponse

from consts.exceptions import LimitExceededError, AgentRunException

from services.agent_service import run_agent

logger = logging.getLogger(__name__)

router = APIRouter()

@router.post("/agent/run")

def run_agent_endpoint(payload: dict):

try:

result = run_agent(payload)

return JSONResponse(status_code=HTTPStatus.OK, content=result)

except LimitExceededError as exc:

raise HTTPException(status_code=HTTPStatus.TOO_MANY_REQUESTS, detail=str(exc))

except AgentRunException as exc:

raise HTTPException(status_code=HTTPStatus.INTERNAL_SERVER_ERROR, detail=str(exc))

```

Service Layer (`backend/services/**/*.py`)

**Purpose:** Implement core business logic orchestration; coordinate repositories/SDKs.

**Requirements:**

**Available Domain Exceptions:**

**Example:**

```python

from typing import Any, Dict

from consts.exceptions import LimitExceededError, AgentRunException, MemoryPreparationException

def run_agent(task_payload: Dict[str, Any]) -> Dict[str, Any]:

"""Run agent core workflow and return domain result dict."""

if _is_rate_limited(task_payload):

raise LimitExceededError("Too many requests for this tenant.")

try:

memory = _prepare_memory(task_payload)

except Exception as exc:

raise MemoryPreparationException("Failed to prepare memory.") from exc

try:

result = _execute_core_logic(task_payload, memory)

except Exception as exc:

raise AgentRunException("Agent execution failed.") from exc

return {"status": "ok", "data": result}

```

File Structure

```

backend/

├── apps/ # HTTP API layer (FastAPI endpoints)

├── services/ # Business logic orchestration

├── consts/

│ ├── const.py # Single source of truth for env vars

│ └── exceptions.py # Domain exceptions

└── utils/

└── auth_utils.py # Authentication utilities

sdk/ # Pure configuration-based, no env vars

```

Migration Checklist

When refactoring existing code to meet these standards:

Environment Variables

1. Add new vars to `backend/consts/const.py`

2. Update `.env.example`

3. Remove all direct `os.getenv()`/`os.environ.get()` outside `const.py`

4. Import from `consts.const` in backend modules

5. Pass configuration as parameters to SDK

6. Remove `from_env()` methods from config classes

Code Quality

1. Convert all non-English comments to English

2. Ensure docstrings use proper English grammar

3. Add module-level loggers: `logger = logging.getLogger(__name__)`

4. Follow existing async/sync conventions in each module

Validation Rules

When reviewing or writing code, verify:

Implementation Steps

When applying this skill to new features:

1. **Start with domain exceptions** - Define any new exceptions in `consts/exceptions.py`

2. **Add environment variables** - Register in `const.py` and `.env.example`

3. **Write service layer** - Implement business logic, raise domain exceptions, return plain objects

4. **Build app layer** - Create FastAPI endpoints, map exceptions to HTTP status codes

5. **Pass config explicitly** - Services inject config into SDK modules via parameters

6. **English documentation** - Write all comments and docstrings in clear English

7. **Add logging** - Use module-level loggers for observability