---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- client/oliver
- domain/ai
- status/active
- tech/azure-ad
- tech/claude
- tech/docker
- tech/fastapi
- tech/gemini
- tech/postgresql
- tech/react
- tech/typescript
- type/project
type: project
---

# Activation Calendar Helper — Developer Manual

## Architecture Overview

The application is a **hybrid stack**:

1. **Backend**: Python FastAPI application running in Docker.
   - Handles API endpoints (`/api/*`), WebSocket connections (`/ws`), and authentication.
   - Manages database interactions (PostgreSQL) and AI service integrations.
2. **Frontend**: React application (TypeScript) served via Apache/Nginx as static files.
   - Handles UI, state management (Zustand), and MSAL authentication.
   - Communicates with the backend via REST API and WebSockets.
3. **Infrastructure**: Docker Compose for local/dev environment orchestration.
   - `postgres`: Data persistence.
   - `app`: FastAPI container.

## Tech Stack

- **Backend**: Python 3.11+, FastAPI, SQLAlchemy, MSAL (Azure AD), OpenAI/Gemini/Claude SDKs.
- **Frontend**: React 18+, TypeScript, Vite, Handsontable (Spreadsheets), MSAL React, Zustand (State).
- **Database**: PostgreSQL 16.
- **Auth**: Azure AD (MSAL PKCE flow).

## Local Setup

### Prerequisites
- Docker & Docker Compose.
- Node.js 18+.
- Python 3.11+.

### Steps

1. **Clone Repository**:
   ```bash
   git clone <repo-url>
   cd ac-helper
   ```

2. **Environment Configuration**:
   ```bash
   cp .env.example .env
   cp frontend/.env.example frontend/.env
   ```
   - Fill in `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_REDIRECT_URI`.
   - Add API keys for desired AI providers (`OPENAI_API_KEY`, `GEMINI_API_KEY`, etc.).
   - Set `ADMIN_EMAIL` for initial bootstrap.

3. **Start Backend**:
   ```bash
   docker-compose up -d
   ```
   - DB will be available at `localhost:5432`.
   - API will be available at `http://localhost:${APP_PORT:-8100}`.

4. **Start Frontend**:
   ```bash
   cd frontend
   npm install
   npm run dev
   ```
   - Frontend will run on `localhost:5173` and proxy API requests to `localhost:${APP_PORT}`.

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `AZURE_TENANT_ID` | Azure AD Tenant ID | Yes |
| `AZURE_CLIENT_ID` | Azure AD App Client ID | Yes |
| `AZURE_REDIRECT_URI` | Callback URL | Yes |
| `OPENAI_API_KEY` | OpenAI API Key | Optional |
| `GEMINI_API_KEY` | Google Gemini API Key | Optional |
| `ANTHROPIC_API_KEY` | Anthropic API Key | Optional |
| `EMERGENCY_TOKEN` | Token for SSO bypass | Optional |
| `POSTGRES_PASSWORD` | Database password | Yes |

## Key Services & Entry Points

- **`backend/main.py`**: FastAPI app entry point. Registers routers (`/api/auth`, `/api/data`, `/api/ai`, etc.).
- **`frontend/src/main.tsx`**: React app entry point. Initializes MSAL provider and Handsontable modules.
- **`frontend/src/stores/useAuthStore.ts`**: Manages user state and token refresh logic.
- **`frontend/src/api/client.ts`**: Axios instance with interceptors for token injection and error handling.

## API Reference

- **`POST /api/auth/login`**: Initiates Microsoft Login.
- **`GET /api/auth/config`**: Returns MSAL configuration for the frontend.
- **`GET /api/data/sheets`**: Lists all sheets.
- **`GET /api/data/sheets/{id}`**: Retrieves sheet data.
- **`POST /api/data/sheets`**: Creates a new sheet.
- **`POST /api/ai/extract`**: Uploads a PDF for AI extraction.
- **`WS /ws`**: WebSocket endpoint for real-time updates.

## Deployment

### Production (Apache/Nginx)

1. **Build Frontend**:
   ```bash
   cd frontend
   npm run build
   ```
   Output goes to `frontend/dist`.

2. **Configure Web Server**:
   - Serve `frontend/dist` as static files.
   - Proxy `/api/*` and `/ws/*` to the Docker container's `APP_PORT` (default 8100).

3. **Docker**: 
   - Set `APP_PORT` in `.env` to match your host port binding.
   - Ensure `POSTGRES_PASSWORD` is secure.
   - Configure `AZURE_REDIRECT_URI` to the production URL.

4. **Restart**: `docker-compose up -d`.

## Known Gotchas

- **MSAL Redirects**: Ensure `AZURE_REDIRECT_URI` exactly matches the registered Azure App URI. Dev mode requires `http://localhost:5173/ac-helper/` (if proxied) or similar.
- **CORS**: The backend must be configured to allow requests from the frontend origin.
- **File Permissions**: The `data/` volume in Docker must be writable by the app user.
- **AI Rate Limits**: High usage of AI extraction may hit API rate limits. Implement retry logic (already partially implemented via `OPENAI_MAX_RETRIES`).
- **Dependent Dropdowns**: Changing a "Category" or "Media" may invalidate dependent cells. Validate data integrity on import/export.

## Related
- [[01 Projects/ac-tool/DEVELOPER_MANUAL]]
- [[01 Projects/ppt-tool/DEVELOPER_MANUAL]]
- [[01 Projects/gmal-scope-builder/DEVELOPER_MANUAL]]
- [[01 Projects/ac-tool/DEVELOPER_MANUAL.md]]
- [[01 Projects/oliver-ai-assistant/DEVELOPER_MANUAL.md]]
- [[01 Projects/ac-helper/DEVELOPER_MANUAL.md]]