---
auto_generated: true
created: 2026-05-19
manual_updated_at: 2026-05-19
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- client/oliver
- domain/devops
- domain/security
- tech/azure-ad
- tech/docker
- tech/postgresql
- tech/python
- type/project
type: project
---

# CC Dashboard Developer Manual

## Architecture Overview

CC Dashboard is a full-stack web application consisting of:

1.  **Backend:** Likely a Python (FastAPI/Flask) or Node.js server (inferred from `.env` structure, `src/` layout, and Vite build artifacts). It handles SSO authentication, database interactions, Azure DevOps API calls, and AI report generation.
2.  **Frontend:** A Vue.js application built with Vite, styled with Tailwind CSS, and utilizing Lucide icons.
3.  **Database:** PostgreSQL 16 (Alpine image), managed via Docker.
4.  **Infrastructure:** Docker Compose for local development and container orchestration.

## Tech Stack

*   **Frontend:** Vue 3 (Composition API), Tailwind CSS, Vite.
*   **Backend:** Inferred from `.env` variables: Likely Python (due to `DB_PASSWORD` and standard JWT setups) or Node.js. Uses `JWT` for session management and `Azure AD` for SSO.
*   **Database:** PostgreSQL 16.
*   **Integrations:**
    *   **Azure AD:** For SSO.
    *   **Azure DevOps:** For project data synchronization.
    *   **Mailgun:** For sending emails (reports, notifications).
    *   **Anthropic Claude:** For AI-driven report generation.

## Local Setup

1.  **Prerequisites:** Docker, Docker Compose.
2.  **Clone and Configure:**
    ```bash
    git clone <repo-url>
    cd cc-dashboard
    cp .env.example .env
    ```
3.  **Set Environment Variables:**
    *   Generate a `SECRET_KEY` using `openssl rand -hex 32`.
    *   Set your `DB_PASSWORD`.
    *   Fill in `ADO_PAT` (Azure DevOps Personal Access Token) if you plan to sync project data.
    *   Fill in `ANTHROPIC_API_KEY` if you want to use AI reports.
4.  **Start Services:**
    ```bash
    docker-compose up --build
    ```
5.  **Access the App:**
    *   Open `http://localhost:8800` (or your configured `BASE_PATH`) in your browser.

## Environment Variables

| Variable | Description | Required |
| :--- | :--- | :--- |
| `DB_PASSWORD` | Password for the PostgreSQL database. | Yes |
| `SECRET_KEY` | JWT signing secret. Generate with `openssl rand -hex 32`. | Yes |
| `DEBUG` | Set to `true` to enable debug mode. | No |
| `BASE_PATH` | The URL path where the app is served (e.g., `/cc-dashboard`). | No |
| `AZURE_TENANT_ID` | Azure AD Tenant ID for the Oliver tenant. | Yes |
| `AZURE_CLIENT_ID` | Azure AD Client ID. | Yes |
| `ALLOWED_EMAIL_DOMAIN` | Restricts login to emails ending in this domain (e.g., `oliver.agency`). | Yes |
| `ADMIN_EMAILS` | Comma-separated list of emails that get admin role on first login. | No |
| `DEV_AUTH_BYPASS` | Set to `true` to bypass SSO for local development. | No |
| `DEV_USER_EMAIL` | Email to auto-login as when `DEV_AUTH_BYPASS` is true. | No |
| `ADO_ORGANIZATION` | Azure DevOps Organization name. | No |
| `ADO_PROJECT` | Azure DevOps Project name. | No |
| `ADO_PAT` | Azure DevOps Personal Access Token. | No |
| `ADO_SYNC_INTERVAL_MINUTES` | How often to sync data from Azure DevOps. | No |
| `MAILGUN_API_KEY` | Mailgun API key for sending emails. | No |
| `ANTHROPIC_API_KEY` | Key for Anthropic Claude API. | No |

## Key Services & Entry Points

### Authentication (`admin-da0oH3jF.js`)
*   Admin functionality is exposed via the `Admin` export in `admin-da0oH3jF.js`.
*   Functions include `users()`, `keys()`, `createKey()`, and `revokeKey()`.
*   These call backend endpoints like `/api/admin/users` and `/api/keys`.

### Calendar & Tasks (`CalendarView-BgDKCOhT.js`, `tasks-BST2hDDN.js`)
*   The calendar logic is complex, involving lane assignment algorithms (`Be` function) to visualize overlapping tasks.
*   Data fetching is handled via `ye.calendar()` which calls an internal API.
*   Uses `lucide-vue-next` for icons (CalendarIcon, ChevronLeftIcon, etc.).

### Azure DevOps Sync (`devops-BEVBwCVu.js`)
*   Handles communication with Azure DevOps.
*   Likely uses the `ADO_PAT` and `ADO_ORGANIZATION` env vars to fetch work items. Sync is periodic based on `ADO_SYNC_INTERVAL_MINUTES`.

### Email Reports (`mailgun` section in `.env`)
*   Uses Mailgun to send daily/weekly reports.
*   Configuration: `MAILGUN_DOMAIN`, `MAILGUN_FROM`.

## API Reference

*   **GET** `/api/admin/users`: List all users.
*   **GET** `/api/keys`: List API keys.
*   **POST** `/api/keys`: Create a new API key.
*   **DELETE** `/api/keys/{id}`: Revoke an API key.
*   **GET** `/api/calendar`: Fetch calendar data (supports `from`, `to`, `view` query params).

## Deployment

1.  **Docker:**
    *   The `Dockerfile` (not provided but implied) builds the Vue app and serves it.
    *   `docker-compose.yml` manages the app and database containers.
    *   Static files are mounted via volume `./src/static:/app/src/static:ro` for hot-reloading in development.
2.  **Production Considerations:**
    *   Ensure `DEBUG=false`.
    *   Use strong `SECRET_KEY` and `DB_PASSWORD`.
    *   Set `ALLOWED_EMAIL_DOMAIN` to restrict access.
    *   Configure reverse proxy (Nginx/Caddy) if not using `BASE_PATH` correctly.

## Known Gotchas

1.  **Static File Mounting:** In development, static files are mounted as read-only (`ro`). Ensure you are editing files in `src/static` and not the build output, or remove the volume mount in production if built into the image.
2.  **Database Health Check:** The DB depends on `service_healthy`. If the database takes longer than 30s (10 retries * 3s timeout) to start, the app container will fail. Adjust `interval` or `retries` if using slow hardware.
3.  **Admin Auto-Role:** Only users in `ADMIN_EMAILS` get admin rights automatically on first login. Subsequent logins do not check this list again.
4.  **Dev Bypass:** Never enable `DEV_AUTH_BYPASS=true` in production. It completely ignores SSO.
5.  **Calendar Algorithm:** The lane assignment algorithm (`Be` function in `CalendarView`) assumes tasks are sorted by start time. Ensure backend returns tasks sorted chronologically.

## Related

- [[01 Projects/ac-tool/DEVELOPER_MANUAL]]
- [[01 Projects/ac-helper/DEVELOPER_MANUAL]]
- [[01 Projects/oliver-sales-ops-platform/DEVELOPER_MANUAL]]
- [[01 Projects/cc-dashboard/USER_MANUAL.md]]