# campflowToolbox

A powerful, multi-tenant administrative toolbox for [campflow](https://campflow.de), designed to streamline camp management, automated reporting, and communication for youth organizations.

## 🎯 Goals & Features

The primary goal of **campflowToolbox** is to bridge the gap between Campflow's raw data and the administrative needs of local groups and units. It provides a centralized dashboard for managing multiple Campflow accounts (Groups) with a focus on security and automation.

### Key Features:
- **Multi-Tenant Architecture**: Manage multiple Campflow groups from a single installation. Each group can have its own Campflow API credentials and settings.
- **Google OAuth 2.0 Authentication**: Secure login using Google accounts.
- **Resource-Centric Authorization**: Access control is dynamically managed via Google Groups. Membership in a specific Google Group grants access to the corresponding Campflow data.
- **Event Dashboard**: A comprehensive view of upcoming and past events, including participant statistics and status updates.
- **Automated Statistics Reporting**: Automatically generates and sends statistics emails (with PDF attachments) to stakeholders.
- **Integrated Mailing Service**: Simplified interface for communicating with event participants.
- **Comprehensive Audit Logging**: Every critical action (viewing events, downloading PDFs, sending mails) is logged per group for transparency.
- **Modern UI**: A responsive, clean interface built with FastAPI templates (Jinja2) and modern CSS.

---

## 🚀 Setup Guide

Setting up **campflowToolbox** requires integration with both the Google Cloud Console and the Google Admin Console (Google Workspace).

### 1. Google Cloud Console Setup

1. **Create a Project**: Go to the [Google Cloud Console](https://console.cloud.google.com/) and create a new project.
2. **Configure OAuth Consent Screen**:
   - Navigate to **APIs & Services > OAuth consent screen**.
   - Choose **Internal** (if only for your organization) or **External**.
   - Add the scope `openid`, `email`, and `profile`.
3. **Create OAuth 2.0 Credentials**:
   - Go to **APIs & Services > Credentials**.
   - Click **Create Credentials > OAuth client ID**.
   - Select **Web application**.
   - Add **Authorized Redirect URIs**: `http://localhost:8000/v1/auth/google/callback` (for local dev) and your production URL (e.g., `https://your-app.com/v1/auth/google/callback`).
   - Save the **Client ID** and **Client Secret**.
4. **Create a Service Account**:
   - Go to **IAM & Admin > Service Accounts**.
   - Click **Create Service Account**.
   - After creation, go to the **Keys** tab and **Add Key > Create new key (JSON)**.
   - Download this file; you will need it for the `GOOGLE_SERVICE_ACCOUNT_FILE` env variable.
   - **Note the Client ID** of this service account for the next step.
5. **Enable APIs**:
   - Go to **APIs & Services > Library**.
   - Search for and enable **Admin SDK API**.

### 2. Google Admin Console Setup (Workspace)

The toolbox needs permission to check if a user is a member of a specific Google Group.

1. **Domain-Wide Delegation**:
   - Open the [Google Admin Console](https://admin.google.com/).
   - Go to **Security > Access and data control > API controls**.
   - Click **Manage Domain Wide Delegation**.
   - Click **Add new**.
   - Enter the **Client ID** of the Service Account created in the previous section.
   - Add the following OAuth scopes:
     - `https://www.googleapis.com/auth/admin.directory.group.readonly`
     - `https://www.googleapis.com/auth/admin.directory.user.readonly`
   - Click **Authorize**.
2. **Setup Google Groups**:
   - Create one or more Google Groups (e.g., `campflow-admins@yourdomain.com`).
   - Members added to these groups will be granted access to the toolbox features for that specific group.

### 3. Local Development Setup

1. **Clone the repository**:
   ```bash
   git clone <repo-url>
   cd campflowToolbox
   ```
2. **Install dependencies**:
   ```bash
   uv sync
   ```
3. **Configure Environment Variables**:
   - Copy `.env_example` to `.env`.
   - Fill in the required values from your Google Cloud Console and Google Admin setup.
   - For `GOOGLE_ADMIN_EMAIL`, use the email of a Workspace Administrator (required for delegation).
4. **Initialize Database**:
   ```bash
   uv run alembic upgrade head
   ```
5. **Run the Application**:
   ```bash
   # Using Docker
   docker compose up
   
   # Or manually
   uv run fastapi dev src/main.py
   ```

---

## 🛠️ Tools & Quality Checks

The project maintains high code quality standards:
- **Ruff**: Linting and formatting.
- **Mypy**: Strict type checking.
- **Pytest**: Automated testing suite.
- **Pre-commit**: Local verification before commits.

Run all checks using:
```bash
uv run pre-commit run --all-files
```

---

## 📄 License
This project is licensed under the MIT License.