# exadel-inc/compreface architecture

> Architecture diagram of the GitHub repository exadel-inc/compreface, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/exadel-inc/compreface
- Repository: https://github.com/exadel-inc/compreface

## Overview

##### Project type and purpose
- CompreFace is a full-stack, Docker-based face recognition system
- Provides REST APIs for detection, recognition, verification, landmark, mask, pose, age/gender
- Delivers a management UI (Angular), two Java microservices (Admin & TrainService), a Python embedding-calculator service, pluggable ML containers, and Postgres DB
- Orchestrated with docker-compose for CPU/GPU, with optional cloud deployments and load-testing/monitoring

##### File structure
- Top-level: docker configs, .env, docker-compose.yml, CI/CD pipelines under .github/workflows
- Custom-builds folder: multiple model plugin containers (FaceNet, InsightFace, Mobilenet, etc.) with their own Dockerfiles & docker-compose
- dev folder: dev-oriented compose files, Nginx templates, startup scripts, multi-platform configs
- db folder: Postgres Dockerfile & init scripts
- java/common, java/admin, java/api: Maven-based Java projects
– common: shared entities, DTOs, exceptions, Feign clients
– admin: Spring Boot service for user/app/role management + OAuth2
– api (TrainService): Spring Boot service exposing core face APIs, caches, async, migration, notifications
- embedding-calculator: Python Flask microservice for on-the-fly embedding computations
- ui: Angular application with Nginx Dockerfiles for dev/prod, feature-based modules, NgRx store for state management
- load-tests: K6 scenarios, Grafana dashboards for performance monitoring

##### README insights
- Confirms Docker-Compose architecture, CPU/GPU support, plugin-based models
- Points to docs/Architecture-and-scalability.md for high-level architecture
- Highlights REST API, role management, and plugin extensibility

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        Browser["Client Browser"]:::client
        NginxUI["Nginx Reverse Proxy\n(UI)"]:::proxy
        AngularUI["Angular UI\n(ui/src/)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        AdminService["Java Admin Service\n(Spring Boot + OAuth2)"]:::service
        TrainService["Java TrainService API\n(Spring Boot)"]:::service
        Cache["EHCache"]:::cache
    end

    %% ML/Inference Layer
    subgraph "ML/Inference Layer"
        Embedding["Python Embedding-Calculator\n(Flask)"]:::service
        subgraph "ML Plugins"
            FaceNet["FaceNet Plugin"]:::plugin
            MobileNet["MobileNet Plugin"]:::plugin
            InsightFace["InsightFace Plugin"]:::plugin
        end
    end

    %% Data Layer
    Postgres["PostgreSQL"]:::db

    %% External Layer
    S3["S3 (Stats)"]:::external
    Analytics["Appery Analytics"]:::external

    %% Monitoring/Load Testing
    subgraph "Monitoring/Load Testing"
        K6["K6 Load Tests"]:::monitor
        Grafana["Grafana Dashboards"]:::monitor
    end

    %% Connections
    Browser -->|HTTP/HTTPS| NginxUI
    NginxUI -->|"Serves UI"| AngularUI
    NginxUI -->|"API Admin"| AdminService
    NginxUI -->|"API Train"| TrainService

    AdminService -->|"reads/writes"| Postgres
    TrainService -->|"reads/writes"| Postgres

    TrainService -->|"HTTP"| Embedding
    TrainService -->|"gRPC/HTTP"| FaceNet
    TrainService -->|"gRPC/HTTP"| MobileNet
    TrainService -->|"gRPC/HTTP"| InsightFace
    TrainService -->|"caches"| Cache

    AdminService -->|analytics| S3
    TrainService -->|analytics| S3
    AdminService -->|analytics| Analytics
    TrainService -->|analytics| Analytics

    K6 -->|load tests| NginxUI
    Grafana -->|monitors metrics| AdminService
    Grafana -->|monitors metrics| TrainService
    Grafana -->|monitors metrics| Embedding
    Grafana -->|monitors metrics| FaceNet
    Grafana -->|monitors metrics| MobileNet
    Grafana -->|monitors metrics| InsightFace

    %% Click Events
    click AngularUI "https://github.com/exadel-inc/compreface/tree/master/ui/src/"
    click NginxUI "https://github.com/exadel-inc/compreface/blob/master/dev/nginx/templates/nginx.conf.template"
    click AdminService "https://github.com/exadel-inc/compreface/blob/master/java/admin/src/main/java/com/exadel/frs/FrsApplication.java"
    click TrainService "https://github.com/exadel-inc/compreface/blob/master/java/api/src/main/java/com/exadel/frs/TrainServiceApplication.java"
    click Embedding "https://github.com/exadel-inc/compreface/blob/master/embedding-calculator/src/app.py"
    click FaceNet "https://github.com/exadel-inc/compreface/blob/master/custom-builds/FaceNet/docker-compose.yml"
    click MobileNet "https://github.com/exadel-inc/compreface/blob/master/custom-builds/Mobilenet/docker-compose.yml"
    click InsightFace "https://github.com/exadel-inc/compreface/blob/master/custom-builds/SubCenter-ArcFace-*/docker-compose.yml"
    click Postgres "https://github.com/exadel-inc/compreface/tree/master/db/Dockerfile"
    click K6 "https://github.com/exadel-inc/compreface/tree/master/load-tests/docker/tests"
    click Grafana "https://github.com/exadel-inc/compreface/blob/master/load-tests/grafana/provisioning/dashboards/*.json"

    %% Styles
    classDef client fill:#a2d2ff,stroke:#0366d6,color:#000
    classDef frontend fill:#ffd6a5,stroke:#d65f00,color:#000
    classDef proxy fill:#caffbf,stroke:#2e7d32,color:#000
    classDef service fill:#ffadad,stroke:#d90429,color:#000
    classDef cache fill:#fdffb6,stroke:#c9184a,color:#000
    classDef plugin fill:#bde0fe,stroke:#1d3557,color:#000
    classDef db fill:#cdb4db,stroke:#480d4f,color:#000
    classDef external fill:#ffc6ff,stroke:#6a4c93,color:#000
    classDef monitor fill:#9bf6ff,stroke:#0077b6,color:#000
```
