---
auto_generated: true
created: 2026-05-19
manual_updated_at: 2026-05-19
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- client/pimco
- tech/azure-ad
- tech/claude
- tech/docker
- tech/fastapi
- tech/python
type: reference
---

# PIMCO Chart Generator Developer Manual

## Architecture Overview
The PIMCO Chart Generator is a FastAPI-based web application that integrates an AI layer (Anthropic Claude) with a deterministic rendering engine. The architecture follows a pipeline pattern:

1. **Input Layer**: Accepts file uploads and text briefs via HTTP.
2. **Data Processing Layer**: Loads, validates, and summarizes data using pandas.
3. **AI Layer**: Uses Claude Opus to interpret data summaries and briefs into a structured `ChartSpec` JSON object.
4. **Validation Layer**: Validates the `ChartSpec` against a schema and the underlying data.
5. **Rendering Layer**: Converts the `ChartSpec` into an SVG using the `drawsvg` library and custom layout algorithms.

## Tech Stack
- **Backend**: Python 3.10+, FastAPI, Uvicorn
- **Database/State**: In-memory session storage (Redis could be added for scaling)
- **AI**: Anthropic Claude API (specifically `claude-opus-4-6`)
- **Data Processing**: pandas, openpyxl
- **Rendering**: drawsvg (SVG generation)
- **Authentication**: Microsoft Azure AD (OAuth2)
- **Containerization**: Docker, Docker Compose

## Local Setup

### Prerequisites
- Python 3.10+
- Docker and Docker Compose (for containerized setup)
- Git

### Installation

1. **Clone the Repository**:
   ```bash
   git clone <repo_url>
   cd pimco-chart-generator
   ```

2. **Environment Configuration**:
   ```bash
   cp .env.example .env
   ```
   Edit `.env` with your specific credentials (see Environment Variables section).

3. **Install Dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

4. **Run Locally**:
   ```bash
   uvicorn app.main:app --reload --host 0.0.0.0 --port 8569
   ```

5. **Run with Docker**:
   ```bash
   docker-compose up --build
   ```

## Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `ANTHROPIC_API_KEY` | API key for Anthropic Claude | `sk-ant-xxx...` |
| `AZURE_TENANT_ID` | Azure AD Tenant ID | `e519c2e6-...` |
| `AZURE_CLIENT_ID` | Azure AD Client ID | `9079054c-...` |
| `AZURE_REDIRECT_URI` | OAuth2 Redirect URI | `https://ai-sandbox.oliver.solutions/Pimco-charts` |
| `SESSION_SECRET_KEY` | Secret for session cookie encryption | `generate via python -c "import secrets; print(secrets.token_hex(32))"` |

## Key Services & Entry Points

### `app/main.py`
- **Entry Point**: FastAPI application initialization.
- **Key Routes**:
  - `GET /`: Serves the login page or main dashboard based on auth state.
  - `POST /generate`: Handles file upload, data loading, AI spec generation, and SVG rendering.
  - `GET /static`: Serves frontend assets.

### `app/data/loader.py`
- **Function**: `load_file(path) -> dict`
- **Purpose**: Reads Excel/CSV files and returns a dictionary of DataFrames (one per sheet).

### `app/data/analyzer.py`
- **Function**: `summarize_data(df) -> dict`
- **Purpose**: Generates a statistical summary of the DataFrame (columns, dtypes, ranges) to feed into the AI prompt.

### `app/ai/brief_interpreter.py`
- **Function**: `interpret_brief(data_summary, brief) -> ChartSpec`
- **Purpose**: Calls the Claude API with the system prompt, data summary, and user brief to generate the initial chart specification.

### `app/renderer/engine.py`
- **Function**: `render_chart(spec, data) -> str`
- **Purpose**: Takes the `ChartSpec` and actual data, computes layout bounds, and generates the SVG string.

### `app/models/chart_spec.py`
- **Purpose**: Defines Pydantic models for `ChartSpec`, `PanelSpec`, `AxisSpec`, `SeriesSpec`, etc., ensuring type safety and validation.

## API Reference

### POST /generate
- **Content-Type**: `multipart/form-data`
- **Parameters**:
  - `file` (File, required): The data file (CSV/Excel).
  - `brief` (str, required): The text description of the desired chart.
  - `sheet` (str, optional): Specific sheet name if multiple sheets exist.
  - `width` (int, optional): Output SVG width (default 2560).
  - `height` (int, optional): Output SVG height (default 1440).
- **Response**: HTML page containing the rendered SVG.

## Deployment

### Docker
The `Dockerfile` and `docker-compose.yml` are configured for production:
- Uses `uvicorn` with `--host 0.0.0.0`.
- Mounts `./output` to `/app/output` for persistent storage of rendered SVGs.
- Healthcheck monitors `http://localhost:8569/`.

### Nginx (Recommended for Production)
Reverse proxy the FastAPI app through Nginx to handle:
- SSL termination.
- Static file serving.
- Load balancing (if scaled).

## Known Gotchas

1. **Font Rendering**: The `drawsvg` library does not support custom font files directly. Ensure the system running the generator has the PIMCO brand fonts (Roboto Condensed, etc.) installed, or embed fonts if modifying the renderer.
2. **Session State**: Sessions are stored in-memory. Restarting the application clears all active sessions. For production, integrate a persistent session store (e.g., Redis).
3. **Azure Auth**: Ensure the `redirect_uri` in Azure Portal exactly matches the `AZURE_REDIRECT_URI` env var, including trailing slashes.
4. **Large Files**: Very large datasets (>100k rows) may slow down the data summarization and AI interpretation steps. Consider sampling or aggregating data before upload.
5. **SVG Complexity**: Extremely complex charts with many series may produce large SVG files. Monitor file sizes for web delivery.

## Related

- [[01 Projects/pimco-charts/USER_MANUAL]]
- [[01 Projects/pimco-charts/USER_MANUAL.md]]