ad1 is a secure, modular platform for intelligent automation of email and document-centric workflows. Built with a focus on Swiss and EU compliance, ad1 leverages AI-powered agents, a robust PostgreSQL database, comprehensive audit trails, and a human-in-the-loop validation process to ensure accuracy and accountability. It supports flexible deployment options, including on-premise and cloud environments.
 Required OAuth Login |
 Landing Page After Login |
 Inbox Page |
 Documents Page |
 Tasks Page |
 IAM Page |
The project is organized into the following main directories:
backend/: Contains the FastAPI application, which houses the core business logic, AI agents, API endpoints, and websocket services.frontend/: Includes the React/Vite user interface, providing the user-facing components for interacting with the system.docs/: Stores all project documentation, including technical specifications, guides, and diagrams.db/: Contains database initialization scripts and schema definitions for PostgreSQL.mcp/: Houses the MCP (Mail Control Protocol) server, responsible for email integration and real-time communication.iac/: Includes Infrastructure as Code (IaC) modules, primarily Terraform, for deploying and managing cloud resources.build/: Contains Docker build files (Dockerfiles) and configurations for containerizing the application components.
- Automated Email Processing: Ingests, classifies, and processes emails based on predefined workflows.
- Intelligent Document Management: Extracts data from various document types (PDF, Word, Excel) using AI.
- Workflow Orchestration: Customizable workflows to automate complex business processes.
- Human-in-the-Loop Validation: Ensures accuracy and control by incorporating manual review steps.
- Comprehensive Audit Trails: Logs all system actions for compliance and traceability.
- Secure and Compliant: Designed with Swiss and EU data protection regulations in mind, supporting secure hosting and data handling.
This section serves as a central hub for all project-related documentation.
Existing Documents:
- Database Schema: Detailed description of database tables and relationships.
- Original Project Briefing: The initial requirements and vision for the project.
- MCP Tools Reference: Technical details about the Mail Control Protocol tools.
- Why Docker?: Explanation of Docker usage within the project.
Upcoming Documents (Placeholders):
- System Architecture: Detailed overview of the system's architecture, components, and interactions. (This will include the Mermaid diagram and details on MCP Server & SSE Transport, Global Email Processing, and Workflow Execution).
- Deployment Guide: Instructions for deploying ad1, including on-premise and cloud scenarios, Google OAuth setup, IaC usage, Docker build/compose details, and troubleshooting tips.
- API Reference: Comprehensive documentation for all backend API endpoints.
- User Management Guide: Details on user and administrator management.
- Workflow Configuration: Guide to configuring and managing automated workflows.
- Full API & Technical Documentation: Placeholder for future Sphinx-generated comprehensive documentation.
Key requirements include Swiss hosting and compliance (GDPR, Swiss DSGVO), use of open-source LLMs, robust orchestration, an agent layer for processing, support for various input/output formats, and a scalable, modular architecture. For full details, refer to the Original Project Briefing.
ad1 features a modular architecture with a FastAPI backend, React frontend, PostgreSQL database, and various supporting services. For a detailed explanation of the system's components, interactions, data flows, email processing, task management, validation mechanisms, and more, please see the System Architecture document. The Mermaid diagram illustrating the architecture has also been moved to this document.
The system processes incoming emails and documents through a series of steps including ingestion, AI-powered processing, human validation, audit logging, and secure output. Detailed workflow descriptions and diagrams can be found in the System Architecture document.
The backend provides a comprehensive REST API for managing emails, documents, validation tasks, audit logs, users, and scheduled workflows. WebSocket support is available for real-time agent interaction. For detailed API endpoint descriptions, request/response formats, and authentication mechanisms, please refer to the API Reference.
The frontend provides interfaces for Inbox management, Document handling, Validation, Audit Trail viewing, Agent Chat, Task Management, and Workflow Building. A more detailed breakdown of frontend components and their relation to the overall architecture can be found in the System Architecture document.
ad1 is designed to meet stringent security and compliance standards:
- Data and servers hosted in Switzerland or compliant EU locations.
- Encryption for data at rest and in transit.
- Adherence to GDPR, Swiss DSGVO, and relevant AI regulations.
- Role-based access control (RBAC) and comprehensive audit trails.
User authentication is handled via Google OAuth. Initial admin users are set via environment variables. Administrators can manage users (create, edit, delete, assign roles) through the UI. Further details will be available in the User Management Guide and API Reference.
ad1 allows users to define custom processing workflows via a dedicated UI. Workflows can be triggered by new emails or scheduled cron jobs, and involve a sequence of configurable steps (e.g., compliance checks, document processing, human verification). More details can be found in the System Architecture and the upcoming Workflow Configuration guide.
Deployment instructions for various environments (on-premise, Google Cloud), including Docker Compose usage, Google OAuth setup, Infrastructure as Code (IaC) with Terraform, and troubleshooting common issues, are consolidated in the Deployment Guide.
- Requirements: Docker, Docker Compose
- Start the system:
docker compose up --build
- Frontend: If developing locally, start the frontend in the
frontend/directory:npm run dev
- Database: Initialized automatically by Docker Compose.
- Access: Open your browser and navigate to the appropriate frontend URL (e.g.,
http://localhost:5173orhttp://localhost:3000).
All rights reserved.
This project is the property of ji-podhead (Leonardo J.). Full usage rights, including distribution, are granted to the orchestra-nexus GitHub organization, or Robert Schröder.
Any other commercial use, resale, or distribution of this software (including SaaS, on-prem, or as part of another product) is strictly prohibited without a written contract with the copyright holder.
Contact the author for licensing options. All rights remain with the project owner.