# 2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization architecture

> Architecture diagram of the GitHub repository 2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization
- Repository: https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization

## Overview

Based on our analysis of the provided file tree and README file, this project is a cloud-based, full-stack media content search and automated tagging system tailored for nonprofits. The system employs a modern architecture that separates concerns into a frontend (built in React), a FastAPI-based backend (with several modular Python scripts handling API endpoints, database operations, and integration with AI and Dropbox), and a Postgres database (managed through Docker). Additionally, there are containerization components (Dockerfiles, docker-compose files) to simplify deployment in both development and production (“release”) environments.

##### Main Components
- Frontend Components:
- Two separate React-based frontend applications (located in frontend/web_app and frontend/web_app_2). These handle the user interface, media uploads, search, and authentication.
- Backend Components:
- The FastAPI server (shown by the primary script api.py) that exposes REST APIs.
- Specific service modules for tasks such as file downloads (download.py), database interactions (db.py, data_models.py), search functionality (search.py), process orchestration (process.py), and structured AI output (structured_llm_output.py).
- Dropbox integration (dropbox_integration.py) signifies integration with external cloud storage.
- Database:
- A Postgres database managed via scripts (DDL.sql, changes_to_db.sql, init-db.sh) and containerized within the “database” directory.
- Infrastructure & Containerization:
- Dockerfiles in backend, frontend, and database directories.
- docker-compose files orchestrating the multi-container environment.
- Nginx is present (with separate configurations in nginx/dev and nginx/release) to route requests between frontend, backend, and external services.
- Supporting Documents and Configurations:
- Documentation files, user guides, and configurations for linting (pre-commit, prettier, eslint) that ensure code quality.

##### Relationships and Data Flow
- The frontend (both web apps) communicates with the backend API endpoints.
- The FastAPI backend processes requests, interacts with the Postgres database for storing/retrieving tagged media data, and calls AI modules (CLIP, GPT-4 Mini, Llama-3.1) for automated tagging and metadata extraction.
- There is a direct integration with the Dropbox API for both file upload and management.
- The Nginx server acts as an entry point and proxy server, directing incoming HTTP traffic to the appropriate container (frontend or backend) based on the URL paths.
- Docker Compose is used to start and interconnect these containers in both development and production (release) modes.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The system splits responsibilities between UI (frontend), business logic (backend), data-storage (database), and external integrations (Dropbox, AI models).
- Containerization: Using Docker and docker-compose to ensure consistency across environments.
- Microservice-like Modularity: Even though it is a monolithic repository, different backend modules handle distinct responsibilities.
- API-First Design: The backend exposes REST endpoints that the frontend calls.

##### Relevant Technologies, Frameworks, and Libraries
- Frontend: React.js, Vite, TailwindCSS, ESLint/PostCSS for builds and styling.
- Backend: FastAPI (Python), Uvicorn for ASGI server functionality, integration with various Python libraries for AI functionalities.
- Database: Postgres alongside migration and initialization scripts.
- Containerization: Docker, docker-compose.
- Reverse Proxy: Nginx to manage HTTP routing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser("User (Browser)"):::external
    Browser -->|"request"| Nginx("Nginx Proxy"):::nginx

    subgraph "Deployment (Docker Compose)"
        Nginx
        subgraph "Frontend Container"
            WebApp1("Web App 1 (React)"):::frontend
            WebApp2("Web App 2 (React)"):::frontend
        end
        subgraph "Backend Container"
            FastAPI("FastAPI Server"):::backend
            Download("File Download Service"):::backend
            DBOps("Database Operations & Data Models"):::backend
            Search("Search Functionality"):::backend
            Process("Process Orchestration"):::backend
            StructuredAI("Structured AI Module"):::backend
            Dropbox("Dropbox Integration"):::backend
        end
        Postgres("Postgres Database"):::database
    end

    Nginx -->|"routes to"| WebApp1
    Nginx -->|"routes to"| FastAPI

    FastAPI -->|"calls"| Download
    FastAPI -->|"calls"| DBOps
    FastAPI -->|"calls"| Search
    FastAPI -->|"calls"| Process
    FastAPI -->|"calls"| StructuredAI
    FastAPI -->|"calls"| Dropbox
    FastAPI -->|"queries"| Postgres

    StructuredAI -->|"invokes"| AINode("External AI Services (CLIP, GPT-4Mini, Llama-3.1)"):::external

    subgraph "Deployment Configuration"
        FrontDocker("Frontend Dockerfile"):::deployment
        BackDocker("Backend Dockerfile"):::deployment
        DbDocker("Database Dockerfile"):::deployment
        DockerCompose("Docker Compose Files"):::deployment
        NginxDev("Nginx Dev Config"):::deployment
        NginxRelease("Nginx Release Config"):::deployment
        NginxDocker("Nginx Release Dockerfile"):::deployment
        DBSchema("Database Schema & Init"):::database
    end

    WebApp1 ---|"built using"| FrontDocker
    FastAPI ---|"built using"| BackDocker
    Postgres ---|"built using"| DbDocker
    Nginx ---|"configured by"| NginxDev
    Nginx ---|"configured by"| NginxRelease
    Nginx ---|"configured by"| NginxDocker
    DockerCompose ---|"orchestrates"| Nginx
    DockerCompose ---|"orchestrates"| WebApp1
    DockerCompose ---|"orchestrates"| FastAPI
    DockerCompose ---|"orchestrates"| Postgres
    DBOps ---|"uses"| DBSchema

    click WebApp1 "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/tree/main/frontend/web_app"
    click WebApp2 "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/tree/main/frontend/web_app_2"
    click FastAPI "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/backend/api.py"
    click Download "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/backend/download.py"
    click DBOps "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/backend/db.py"
    click DBOps "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/backend/data_models.py"
    click Search "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/backend/search.py"
    click Process "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/backend/process.py"
    click StructuredAI "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/backend/structured_llm_output.py"
    click Dropbox "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/backend/dropbox_integration.py"
    click DBSchema "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/backend/DDL.sql"
    click DBSchema "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/database/changes_to_db.sql"
    click DBSchema "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/database/init-db.sh"
    click FrontDocker "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/tree/main/frontend/Dockerfile"
    click BackDocker "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/tree/main/backend/Dockerfile"
    click DbDocker "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/tree/main/database/Dockerfile"
    click DockerCompose "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/docker-compose.yml"
    click DockerCompose "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/docker-compose.override.yml"
    click DockerCompose "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/docker-compose.release.yml"
    click NginxDev "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/nginx/dev/nginx.conf"
    click NginxRelease "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/blob/main/nginx/release/nginx.conf"
    click NginxDocker "https://github.com/2024-arizona-opportunity-hack/harora-pajaritoenvironmenta-frommediaoverloadtoseamlessorganization/tree/main/nginx/release/Dockerfile"

    classDef frontend fill:#CEF6F5,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#D5F5E3,stroke:#145A32,stroke-width:2px;
    classDef database fill:#FCF3CF,stroke:#B9770E,stroke-width:2px;
    classDef deployment fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef nginx fill:#D6EAF8,stroke:#154360,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
```
