# darkhawk727/cs348-project architecture

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

- Interactive diagram: https://gitdiagram.com/darkhawk727/cs348-project
- Repository: https://github.com/darkhawk727/cs348-project

## Overview

##### Project Type and Purpose
- This is a full-stack application focused on database query and visualization functionality.
- The README instructs to “streamlit run app.py” so the UI is built with Streamlit, and it requires Pandas and DuckDB.
- The application is designed to let end users interact with movie data using SQL queries and custom query pages.

##### Main Components
a. User Interface / Application Layer
- app.py: The main entry-point for the Streamlit application.
- queryPages package: Contains modules such as actors.py, films.py, recommendations.py, etc. Each module likely corresponds to a specific “page” in the app where the user can view or interact with different aspects of the movie data.

b. Data Layer
- Data folder: Contains CSV files (e.g., actor.csv, film.csv, users.csv) along with SQL files (data.sql, schema.sql) that define the database schema. It also includes a pre-built database file (movies.db) which the app likely queries.

c. Query Execution and Script Layer
- queries folder: Holds SQL scripts (e.g., actor_explorer.sql, movie_recommendations.sql) as well as Python scripts (e.g., film_query.py) to run or manage queries.
- These scripts form the core layer that encapsulates the SQL logic used by the application.

d. Testing and Validation Layer
- tests and test.py: These directories and files contain tests (both feature tests and sample tests with inputs/outputs) that validate the SQL queries and possibly the end-to-end functionality of the app.

e. Reporting and Documentation
- reports directory and README: Provide project documentation and milestone reports which give context on development progress and design decisions.

##### Relationships and Data Flow
- End users interact with the application via the Streamlit interface (app.py).
- The UI routes user requests to specific pages defined in the queryPages package.
- Each query page module calls underlying query scripts (from the queries directory) to fetch or manipulate data.
- These query scripts interact with the data layer (the DuckDB database and CSV files) either directly or via pre-defined SQL queries.
- Results are then displayed back in the application's UI.
- Testing scripts ensure that the flow from the UI through query execution to data retrieval works as expected.

##### Architectural Patterns and Design Principles
- Separation of Concerns: UI (app.py and queryPages) is clearly separated from business logic (query scripts) and data storage (data folder).
- Modular Design: Individual query pages and separate SQL scripts make it easy to extend functionality (as seen in the TODO list such as custom SQL queries, adding indexes, views, etc.).
- Data-Driven Processing: Heavy reliance on SQL and data files underscores the importance of the data layer in the overall architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Application Layer"
        UI["app.py (Streamlit UI)"]:::ui
        QP["queryPages (Pages: actors, films, recommendations, ... )"]:::frontend
    end

    subgraph "Backend Services"
        QS["queries (SQL & Python Query Scripts)"]:::backend
        DS["data (CSV, SQL schema, movies.db)"]:::database
    end

    subgraph "Auxiliary"
        T["tests & test.py (Testing)"]:::test
        R["README & reports (Documentation)"]:::doc
    end

    UI -->|"calls"| QP
    QP -->|"invokes"| QS
    QS -->|"executes_query_on"| DS
    DS -->|"returns_results"| QS
    QS -->|"sends_results"| QP
    QP -->|"updates_view"| UI

    T -->|"validates"| QS
    T -->|"tests"| UI
    UI -->|"documented_in"| R
    QS -->|"documented_in"| R

    classDef ui fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef frontend fill:#85C1E9,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef database fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef test fill:#F5B7B1,stroke:#CB4335,stroke-width:2px;
    classDef doc fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;

    click UI "https://github.com/darkhawk727/cs348-project/blob/main/app.py"
    click QP "https://github.com/darkhawk727/cs348-project/tree/main/queryPages/"
    click QS "https://github.com/darkhawk727/cs348-project/tree/main/queries/"
    click DS "https://github.com/darkhawk727/cs348-project/tree/main/data/"
    click T "https://github.com/darkhawk727/cs348-project/tree/main/tests/"
    click R "https://github.com/darkhawk727/cs348-project/blob/main/README.md"
```
