# seanyap90/crud_pdf architecture

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

- Interactive diagram: https://gitdiagram.com/seanyap90/crud_pdf
- Repository: https://github.com/seanyap90/crud_pdf

## Overview

##### Project Type & Purpose
- The README hints at features for handling digital copies (e.g., PDF uploads) and handwritten notes extraction, along with an IoT administrator dashboard. This indicates a full-stack application that supports document processing and IoT management.
- The file tree confirms two frontend applications: one under the “client” directory (likely for PDF uploads/status review) and another under “iot-client-admin” (an IoT dashboard for managing gateways and end devices). The backends in “src” include services for file APIs and IoT functionalities.

##### Analyzing the File Structure
- Frontend Components:
- The “client” directory holds a Next.js-based application with clearly defined components (Layout, PDFUpload, StatusList, etc.) and supporting libraries.
- The “iot-client-admin” directory is another Next.js application with a more extensive set of UI components, hooks, and tailored pages for analytics and gateway management.
- Backend Services:
- The “src/files_api” folder contains a Python-based service that handles file uploads, S3 interactions (with modules for reading, writing, deleting, and event notifications), and possibly PDF extraction and processing.
- The “src/iot” folder includes multiple modules:
- A Python core (main.py, models, routes) that likely orchestrates IoT related operations.
- A “gateway” subdirectory with Go source code (Dockerfile, go.mod, main.go) to handle specific IoT gateway functionality.
- A “rules_engine” submodule (also in Go) that processes rules or events from IoT devices.
- A “worker” module (in Python), which integrates with AWS or local processing for IoT events.
- A “src/database” module contains event store and local database configurations used by the APIs.
- CI/CD, Testing & Tools:
- There are GitHub Actions configuration files (.github/workflows) and a Makefile for build/deployment automation.
- Test directories (both e2e and unit tests) indicate rigorous testing practices across components.

a. Main Components:
- Client Application (Next.js) – Handles digital copy extractions (upload PDF, review status) and user interface features.
- IoT Administrator Dashboard (Next.js) – Provides management for gateways and connected IoT devices.
- Files API Service (Python) – Manages file processing, integrates with AWS S3 for storage and retrieval, and serves PDF and document extraction endpoints.
- IoT Service Components:
- IoT Core (Python) – Manages configurations, models, and routing of IoT device messages.
- Gateway Service (Go) – Interfaces directly with IoT gateways.
- Rules Engine Service (Go) – Processes real-time events and enforces business rules for IoT operations.
- Worker Service (Python) – Implements asynchronous tasks (e.g., AWS integration) for managing IoT data processing.
- Database & Event Store – Manages persistent storage as indicated in “src/database”.
- External/Third-Party Services – Amazon S3 for file storage, AWS services for IoT, and MQTT broker (mosquitto) for messaging as configured in “src/iot/mosquitto”.

b. Relationships & Interactions:
- The “client” and “iot-client-admin” applications communicate via API calls to their respective backend services.
- The Files API Service interacts with storage (AWS S3) and possibly a message queue for asynchronous operations (see “msg_queue.py”).
- IoT components exchange data: The IoT core communicates with the Gateway (Go service) and the Rules Engine. Workers process tasks and update the system state in the event store.
- The Database/Event Store is central to both the file processing and IoT domains, storing events and state-related information.
- Integration with external services (S3, MQTT broker) should be explicitly drawn along the data flow paths.

c. Architectural Patterns & Design Principles:
- Separation of Concerns: Clear division between frontend applications (user interface) and backend services (processing logic, storage, IoT management).
- Microservices: The backend is split into discrete services (files API, IoT core, gateway, rules engine, worker) possibly communicating through REST endpoints or message queues.
- Modularization and Extensibility: Both Next.js frontends are organized with components and hooks, while backends have well-defined modules for APIs, database access, and external integrations.
- Cloud-Native & Containerization: Presence of Dockerfiles and configuration files (for Docker Compose) indicates a containerized deployment approach.

d. Technologies & Frameworks to Highlight:
- Next.js for frontend applications.
- Tailwind CSS for styling, as shown by “tailwind.config.js” and CSS files.
- Python for API services (file processing, IoT core, workers).
- Go for performance-critical components (gateway, rules engine).
- AWS S3 (and potentially AWS IoT services) as key external infrastructure.
- MQTT (via mosquitto) for message brokering in IoT communications.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Applications
    subgraph "Frontend Applications"
        CA["Client Application (Next.js)"]
        IAD["IoT Administrator Dashboard (Next.js)"]
    end

    %% Backend Services
    subgraph "Backend Services"
        FilesAPI["Files API Service (Python)"]
        IoTCore["IoT Core Service (Python)"]
        Gateway["Gateway Service (Go)"]
        RulesEng["Rules Engine Service (Go)"]
        Worker["Worker Service (Python)"]
        Database["Database & Event Store"]
    end

    %% External Services
    subgraph "External Services"
        ExternalS3["External S3"]
        MQTT["MQTT Broker"]
    end

    %% Connections between Frontend and Backend
    CA -->|"calls"| FilesAPI
    IAD -->|"calls"| IoTCore

    %% Connections within File Processing Flow
    FilesAPI -->|"storesFiles"| ExternalS3
    FilesAPI -->|"logsEvents"| Database

    %% Connections within IoT Services
    IoTCore -->|"manages"| Gateway
    IoTCore -->|"routesTo"| RulesEng
    IoTCore -->|"initiatesTasks"| Worker
    IoTCore -->|"updates"| Database

    Gateway -->|"publishesTo"| MQTT

    RulesEng -->|"updates"| Database
    Worker -->|"updates"| Database

    %% Click Events for Component Mapping
    click CA "https://github.com/seanyap90/crud_pdf/tree/main/client/app"
    click IAD "https://github.com/seanyap90/crud_pdf/tree/main/iot-client-admin/app"
    click FilesAPI "https://github.com/seanyap90/crud_pdf/tree/main/src/files_api"
    click IoTCore "https://github.com/seanyap90/crud_pdf/tree/main/src/iot"
    click Gateway "https://github.com/seanyap90/crud_pdf/tree/main/src/iot/gateway"
    click RulesEng "https://github.com/seanyap90/crud_pdf/tree/main/src/iot/rules_engine"
    click Worker "https://github.com/seanyap90/crud_pdf/tree/main/src/iot/worker"
    click Database "https://github.com/seanyap90/crud_pdf/tree/main/src/database"

    %% Styling for clarity and color coding
    classDef frontend fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef backend fill:#A3E4D7,stroke:#16A085,stroke-width:2px;
    classDef db fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;

    class CA,IAD frontend;
    class FilesAPI,IoTCore,Gateway,RulesEng,Worker backend;
    class Database db;
    class ExternalS3,MQTT external;
```
