# cdsl-research/doktor-v2 architecture

> Architecture diagram of the GitHub repository cdsl-research/doktor-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cdsl-research/doktor-v2
- Repository: https://github.com/cdsl-research/doktor-v2

## Overview

##### Project Type and Purpose
- The project is a demo web application built with a microservices architecture. Its primary purpose is to provide search and download functionality for technical reports.
- The README also explicitly states that microservices are deployed on a Kubernetes cluster with Istio utilized as a service mesh, which implies that deployment, inter-service communication, and scaling are key aspects of the design.

##### Key Components
a. Microservices Layers:
- Author Service: Manages authors as indicated by the “author” directory (includes Dockerfile, deployment, and initialization scripts).
- Front Service: Provides the primary Web UI for end users (located in the “front” directory).
- Front-admin Service: Provides a management console (located in the “front-admin” directory).
- Fulltext Service: Powers full-text searching capabilities (from the “fulltext” directory).
- Paper Service: Manages technical papers (from the “paper” directory with its PDF samples and MongoDB initialization).
- Stats Service: Handles access history logs (from the “stats” directory).
- Thumbnail Service: Manages paper-related figures (from the “thumbnail” directory).
- (Though the README mentions “textize” for extracting text from PDFs, this component does not appear in the file tree; you might note it as a possible missing service or an external dependency.)

b. Supporting Components:
- Deployment Scripts: The “deploy” directory contains Kubernetes deployment configurations (namespaces, app definitions, service configurations for each microservice, Istio configuration, etc.).
- Dev Tools: The “dev_tools” directory includes supplementary scripts for tasks like uploading sample data.
- Documentation: The “docs_src” directory features scripts and files to generate API docs and OpenAPI specs.
- CI/CD Pipelines: GitHub workflows and configurations within the “.github” directory indicate build/test/deploy automation.
- Configuration Files & Kubernetes Tools: Files like .kube-linter and various YML files point to quality checks and cluster configurations.

##### Relationships and Interactions
- Each microservice is containerized (evidenced by Dockerfiles and docker-compose.yml files in every primary service directory).
- The services communicate over the network, likely through REST API calls (the existence of OpenAPI JSON files in docs_src supports this).
- The database interactions: Several services (such as author, paper, stats) appear to use MongoDB (initialization scripts and mongo-related deployment YAML files) and possibly MinIO for thumbnail/paper file storage.

##### Architectural Patterns and Design Principles
- Microservice Architecture: Each functional unit (service) is isolated, enabling scalability and independent deployment.
- Containerization and Orchestration: Each service is built into containers with Docker, orchestrated using Kubernetes.
- DevOps Automation: CI/CD pipelines with GitHub workflows ensure continuous integration and quality checks.

##### Implementation Details
- That each component/block is clearly labeled.
- Notes highlighting key details like “Containerized via Docker”, “Deployment via Kubernetes”, and “Service Mesh managed by Istio”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        KUBE["Kubernetes Cluster"]:::infrastructure
        ISTIO["Istio Service Mesh"]:::infrastructure
        CI_CD["CI/CD Pipeline"]:::infrastructure
        KUBE --> ISTIO
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        FRONT["Front Service"]:::service
        FRONT_ADMIN["Front-admin Service"]:::service
    end

    %% Business Services
    subgraph "Business Services"
        AUTHOR["Author Service"]:::service
        FULLTEXT["Fulltext Service"]:::service
        PAPER["Paper Service"]:::service
        STATS["Stats Service"]:::service
        THUMBNAIL["Thumbnail Service"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        MONGO[(MongoDB)]:::database
        MINIO[(MinIO Object Storage)]:::database
    end

    %% Deployment Configurations
    subgraph "Deployment Configurations"
        AUTHOR_DEPLOY["Author Deployment"]:::support
        FRONT_DEPLOY["Front Deployment"]:::support
        FRONT_ADMIN_DEPLOY["Front-admin Deployment"]:::support
        FULLTEXT_DEPLOY["Fulltext Deployment"]:::support
        PAPER_DEPLOY["Paper Deployment"]:::support
        STATS_DEPLOY["Stats Deployment"]:::support
        THUMBNAIL_DEPLOY["Thumbnail Deployment"]:::support
        DEPLOY_SCRIPTS["Deployment Scripts"]:::support
    end

    %% Supporting Tools
    subgraph "Supporting Tools"
        DEV_TOOLS["Dev Tools"]:::support
        DOCS["Documentation Generation"]:::support
        GITHUB["CI/CD (GitHub Workflows)"]:::support
        KUBE_LINTER["Kube Linter/Config Files"]:::support
    end

    %% Service interactions
    FRONT -->|"calls"| PAPER
    FRONT -->|"calls"| FULLTEXT
    FRONT_ADMIN -->|"manages"| AUTHOR
    FRONT_ADMIN -->|"views"| STATS

    AUTHOR -->|"CRUD"| MONGO
    PAPER -->|"CRUD"| MONGO
    STATS -->|"logs"| MONGO
    THUMBNAIL -->|"stores"| MINIO

    %% Deployment associations
    AUTHOR_DEPLOY --> AUTHOR
    FRONT_DEPLOY --> FRONT
    FRONT_ADMIN_DEPLOY --> FRONT_ADMIN
    FULLTEXT_DEPLOY --> FULLTEXT
    PAPER_DEPLOY --> PAPER
    STATS_DEPLOY --> STATS
    THUMBNAIL_DEPLOY --> THUMBNAIL

    DEPLOY_SCRIPTS --> AUTHOR_DEPLOY
    DEPLOY_SCRIPTS --> FRONT_DEPLOY
    DEPLOY_SCRIPTS --> FRONT_ADMIN_DEPLOY
    DEPLOY_SCRIPTS --> FULLTEXT_DEPLOY
    DEPLOY_SCRIPTS --> PAPER_DEPLOY
    DEPLOY_SCRIPTS --> STATS_DEPLOY
    DEPLOY_SCRIPTS --> THUMBNAIL_DEPLOY

    GITHUB --> DEPLOY_SCRIPTS

    %% Class Definitions for styling
    classDef service fill:#BFD7EA,stroke:#333,stroke-width:2px;
    classDef database fill:#F5B7B1,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#82E0AA,stroke:#333,stroke-width:2px;
    classDef support fill:#F9E79F,stroke:#333,stroke-width:2px;

    %% Click Events for Service Code and Deployment Configurations
    click AUTHOR "https://github.com/cdsl-research/doktor-v2/blob/master/author/main.py"
    click AUTHOR_DEPLOY "https://github.com/cdsl-research/doktor-v2/tree/master/deploy/author/"
    click FRONT "https://github.com/cdsl-research/doktor-v2/blob/master/front/main.py"
    click FRONT_DEPLOY "https://github.com/cdsl-research/doktor-v2/tree/master/deploy/front/"
    click FRONT_ADMIN "https://github.com/cdsl-research/doktor-v2/blob/master/front-admin/main.py"
    click FRONT_ADMIN_DEPLOY "https://github.com/cdsl-research/doktor-v2/tree/master/deploy/front-admin/"
    click FULLTEXT "https://github.com/cdsl-research/doktor-v2/blob/master/fulltext/main.py"
    click FULLTEXT_DEPLOY "https://github.com/cdsl-research/doktor-v2/tree/master/deploy/fulltext/"
    click PAPER "https://github.com/cdsl-research/doktor-v2/blob/master/paper/main.py"
    click PAPER_DEPLOY "https://github.com/cdsl-research/doktor-v2/tree/master/deploy/paper/"
    click STATS "https://github.com/cdsl-research/doktor-v2/blob/master/stats/main.py"
    click STATS_DEPLOY "https://github.com/cdsl-research/doktor-v2/tree/master/deploy/stats/"
    click THUMBNAIL "https://github.com/cdsl-research/doktor-v2/blob/master/thumbnail/main.py"
    click THUMBNAIL_DEPLOY "https://github.com/cdsl-research/doktor-v2/tree/master/deploy/thumbnail/"
    click DEPLOY_SCRIPTS "https://github.com/cdsl-research/doktor-v2/tree/master/deploy/"
    click DEV_TOOLS "https://github.com/cdsl-research/doktor-v2/tree/master/dev_tools/sample-data-uploader/"
    click DOCS "https://github.com/cdsl-research/doktor-v2/tree/master/docs_src/"
    click GITHUB "https://github.com/cdsl-research/doktor-v2/tree/master/.github/workflows/"
    click KUBE_LINTER "https://github.com/cdsl-research/doktor-v2/tree/master/.kube-linter/"
```
