# tanvir-mahamood/resourcehub architecture

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

- Interactive diagram: https://gitdiagram.com/tanvir-mahamood/resourcehub
- Repository: https://github.com/tanvir-mahamood/resourcehub

## Overview

1. This repository is a monolithic PHP 8.x web application that sits between users and a private Google Drive. Its core architectural goal is to expose an authenticated, searchable resource catalog without ever exposing raw Drive URLs.

2. The application has three primary external dependencies: Google OAuth 2.0 for user sign-in, Google Drive API v3 via a service account for file and folder access, and MySQL for persistence. Everything else in the repo is application logic, UI rendering, or admin tooling.

3. `index.php` is the main user-facing entry point. It likely handles the landing page, login state, and rendering of the cached folder tree as a browsable resource hierarchy. `index.css` provides the custom UI layer, while Bootstrap and front-end libraries are used for layout, icons, and charts.

4. Authentication is handled by `auth.php`. The flow is OAuth-based rather than password-based: a Google login returns user identity data, which is then stored or updated in the `users` table. The app uses PHP sessions to maintain login state and role checks.

5. Authorization is simple and centralized: regular authenticated users can browse and interact with resources, while admins have access to maintenance and analytics screens. The admin boundary is implemented in `admin/index.php` and reinforced by server-side checks, not just UI hiding.

6. File access is mediated by `proxy.php`, which is the key security boundary in the system. Instead of linking directly to Drive, the app streams file content through the server after checking session/auth context and then retrieves the content from Google Drive using the service account. This keeps Drive links hidden and allows download/view events to be logged.

7. The resource hierarchy is not fetched live on every page request. `refresh_cache.php` crawls the Drive folder tree and stores a JSON representation in `drive_cache`. This cached tree is what makes recursive, nested browsing fast and reduces repeated Drive API calls.

8. User engagement actions are separated into lightweight AJAX-style endpoints. `star.php` toggles star/unstar state and updates counts, while download/view events are recorded in `user_activity_log` and aggregated into `resource_metrics`. The data model supports both per-file metrics and per-user behavior tracking.

9. The database is the app’s state boundary. `db.php` provides the PDO connection used across the app, and `database_schema.sql` defines the persistent entities: users, resource metrics, user stars, activity logs, and the cached Drive tree. `setup_db.php` is a one-time bootstrap path for initializing that schema.

10. The admin dashboard acts as an operational control plane rather than a separate application. It combines database-backed KPIs like total users, downloads over time, top resources, and active users, plus a manual cache refresh control that synchronizes the app with the underlying Drive structure.

11. From a data-flow perspective, the main loop is: Google login creates a session and user row, the cached Drive tree is read from MySQL for browsing, user interactions generate metric writes, and file requests are proxied to Google Drive through the server. The app never gives the browser direct access to the storage backend.

12. Deployment is classic PHP/MySQL hosting with Composer-managed dependencies and environment-specific secrets kept out of version control. `config.php` and the service account JSON are local-only configuration artifacts, which is important because the application depends on both OAuth credentials and Drive access permissions to function securely.

Main entry points: [`database_schema.sql`](https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql) (Schema), [`auth.php`](https://github.com/tanvir-mahamood/resourcehub/blob/main/auth.php) (Sign-in), [`refresh_cache.php`](https://github.com/tanvir-mahamood/resourcehub/blob/main/refresh_cache.php) (Cache refresh), [`db.php`](https://github.com/tanvir-mahamood/resourcehub/blob/main/db.php) (PDO access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core app"]
  node_index["Catalog UI<br/>php entrypoint<br/>[index.php]"]
  node_auth["Sign-in<br/>php oauth<br/>[auth.php]"]
  node_proxy["File proxy<br/>php gateway<br/>[proxy.php]"]
  node_star["Star action<br/>php ajax<br/>[star.php]"]
  node_refresh["Cache refresh<br/>php crawler<br/>[refresh_cache.php]"]
  node_bootstrap["Composer deps<br/>php packages<br/>[composer.json]"]
  node_config["Local config<br/>env config<br/>[config.example.php]"]
  node_assets["UI styles<br/>css<br/>[index.css]"]
end

subgraph group_data["Data layer"]
  node_db[("PDO access<br/>php db<br/>[db.php]")]
  node_schema["Schema"]
  node_setup["Bootstrap DB<br/>php setup<br/>[setup_db.php]"]
  node_users[("Users<br/>table")]
  node_cache[("Drive cache<br/>table")]
  node_metrics[("Metrics<br/>table")]
  node_activity[("Activity log<br/>table")]
  node_stars[("Stars<br/>table")]
end

subgraph group_integration["External services"]
  node_oauth(("Google OAuth<br/>external auth"))
  node_drive(("Google Drive<br/>external storage"))
end

subgraph group_admin["Admin control"]
  node_admin_ui["Admin dashboard<br/>php console<br/>[index.php]"]
end

node_index -->|"reads cache"| node_db
node_index -->|"login flow"| node_auth
node_auth -->|"authenticate"| node_oauth
node_auth -->|"upsert user"| node_users
node_auth -->|"persist session user"| node_db
node_proxy -->|"stream file"| node_drive
node_proxy -->|"log access"| node_db
node_proxy -->|"append event"| node_activity
node_star -->|"toggle star"| node_stars
node_star -->|"update counts"| node_metrics
node_star -->|"log action"| node_activity
node_refresh -->|"crawl tree"| node_drive
node_refresh -->|"write cache"| node_cache
node_refresh -->|"persist tree"| node_db
node_admin_ui -->|"read KPIs"| node_metrics
node_admin_ui -->|"read activity"| node_activity
node_admin_ui -->|"refresh cache"| node_refresh
node_schema -->|"defines"| node_users
node_schema -->|"defines"| node_cache
node_schema -->|"defines"| node_metrics
node_schema -->|"defines"| node_activity
node_schema -->|"defines"| node_stars
node_setup -->|"initializes"| node_schema
node_index -->|"styles with"| node_assets
node_index -->|"loads deps"| node_bootstrap
node_auth -->|"reads secrets"| node_config
node_proxy -->|"reads secrets"| node_config
node_refresh -->|"reads secrets"| node_config
node_admin_ui -->|"reads data"| node_db

click node_index "https://github.com/tanvir-mahamood/resourcehub/blob/main/index.php"
click node_auth "https://github.com/tanvir-mahamood/resourcehub/blob/main/auth.php"
click node_proxy "https://github.com/tanvir-mahamood/resourcehub/blob/main/proxy.php"
click node_star "https://github.com/tanvir-mahamood/resourcehub/blob/main/star.php"
click node_refresh "https://github.com/tanvir-mahamood/resourcehub/blob/main/refresh_cache.php"
click node_admin_ui "https://github.com/tanvir-mahamood/resourcehub/blob/main/admin/index.php"
click node_db "https://github.com/tanvir-mahamood/resourcehub/blob/main/db.php"
click node_schema "https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql"
click node_setup "https://github.com/tanvir-mahamood/resourcehub/blob/main/setup_db.php"
click node_users "https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql"
click node_cache "https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql"
click node_metrics "https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql"
click node_activity "https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql"
click node_stars "https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql"
click node_bootstrap "https://github.com/tanvir-mahamood/resourcehub/blob/main/composer.json"
click node_config "https://github.com/tanvir-mahamood/resourcehub/blob/main/config.example.php"
click node_assets "https://github.com/tanvir-mahamood/resourcehub/blob/main/index.css"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_auth,node_proxy,node_star,node_refresh,node_bootstrap,node_config,node_assets toneBlue
class node_db,node_schema,node_setup,node_users,node_cache,node_metrics,node_activity,node_stars toneAmber
class node_oauth,node_drive toneMint
class node_admin_ui toneRose
```

## Components

### Core app

User-facing browsing, auth, and interaction flow.

- [Catalog UI](https://github.com/tanvir-mahamood/resourcehub/blob/main/index.php): php entrypoint · Main user-facing page for browsing the cached resource hierarchy and rendering the landing/auth state. · `index.php`
- [Sign-in](https://github.com/tanvir-mahamood/resourcehub/blob/main/auth.php): php oauth · Google OAuth login flow; creates or updates user records and establishes the session. · `auth.php`
- [File proxy](https://github.com/tanvir-mahamood/resourcehub/blob/main/proxy.php): php gateway · Server-side download/view boundary that checks session context and streams Drive content without exposing raw URLs. · `proxy.php`
- [Star action](https://github.com/tanvir-mahamood/resourcehub/blob/main/star.php): php ajax · Lightweight endpoint for starring and unstarring resources and updating engagement state. · `star.php`
- [Cache refresh](https://github.com/tanvir-mahamood/resourcehub/blob/main/refresh_cache.php): php crawler · Crawls Google Drive folder structure and rebuilds the cached JSON tree in the database. · `refresh_cache.php`
- [Composer deps](https://github.com/tanvir-mahamood/resourcehub/blob/main/composer.json): php packages · Managed PHP dependencies used by the application runtime. · `composer.json`
- [Local config](https://github.com/tanvir-mahamood/resourcehub/blob/main/config.example.php): env config · Example configuration for secrets and environment-specific settings. · `config.example.php`
- [UI styles](https://github.com/tanvir-mahamood/resourcehub/blob/main/index.css): css · Custom front-end styling for the catalog interface. · `index.css`

### Data layer

Database schema, connection, and cache persistence.

- [PDO access](https://github.com/tanvir-mahamood/resourcehub/blob/main/db.php): php db · Shared database connection used by the application. · `db.php`
- [Schema](https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql): sql schema · Persistent model for users, cached Drive tree, metrics, stars, and activity logs. · `database_schema.sql`
- [Bootstrap DB](https://github.com/tanvir-mahamood/resourcehub/blob/main/setup_db.php): php setup · One-time initialization path for creating and seeding the database schema. · `setup_db.php`
- [Users](https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql): table · Authenticated identities and role state stored after Google sign-in. · `database_schema.sql`
- [Drive cache](https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql): table · Cached folder/file tree used for fast recursive browsing. · `database_schema.sql`
- [Metrics](https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql): table · Aggregated resource counts and usage statistics for the dashboard. · `database_schema.sql`
- [Activity log](https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql): table · Per-user view/download/star events for auditing and aggregation. · `database_schema.sql`
- [Stars](https://github.com/tanvir-mahamood/resourcehub/blob/main/database_schema.sql): table · Per-user favorite state for resources. · `database_schema.sql`

### External services

Google OAuth and Drive integrations.

- **Google OAuth**: external auth · Identity provider used for user sign-in.
- **Google Drive**: external storage · Private document store accessed through a service account and proxied by the app.

### Admin control

Operational dashboard and maintenance actions.

- [Admin dashboard](https://github.com/tanvir-mahamood/resourcehub/blob/main/admin/index.php): php console · Operational screen for KPIs, active users, top resources, and manual maintenance controls. · `admin/index.php`

## Connections

- Catalog UI → PDO access: reads cache · Loads the cached resource tree and related state from MySQL.
- Catalog UI → Sign-in: login flow · Routes unauthenticated users into Google sign-in.
- Sign-in → Google OAuth: authenticate · Delegates identity verification to Google OAuth.
- Sign-in → Users: upsert user · Creates or updates the logged-in user record.
- Sign-in → PDO access: persist session user · Writes user state through the shared database connection.
- File proxy → Google Drive: stream file · Fetches protected file content from Google Drive via service account.
- File proxy → PDO access: log access · Records downloads or views through persistent storage.
- File proxy → Activity log: append event · Creates user activity entries for proxied file requests.
- Star action → Stars: toggle star · Updates per-user star state for a resource.
- Star action → Metrics: update counts · Adjusts aggregated engagement metrics.
- Star action → Activity log: log action · Records star/unstar interactions.
- Cache refresh → Google Drive: crawl tree · Traverses folders and files from Google Drive.
- Cache refresh → Drive cache: write cache · Stores the computed hierarchy as a cached tree.
- Cache refresh → PDO access: persist tree · Writes refreshed cache data through MySQL.
- Admin dashboard → Metrics: read KPIs · Displays dashboard metrics such as downloads and active users.
- Admin dashboard → Activity log: read activity · Uses activity history for operational reporting.
- Admin dashboard → Cache refresh: refresh cache · Triggers manual synchronization of the Drive tree.
- Schema → Users: defines · Declares the users table.
- Schema → Drive cache: defines · Declares the cached Drive tree table.
- Schema → Metrics: defines · Declares the metrics table.
- Schema → Activity log: defines · Declares the user activity log table.
- Schema → Stars: defines · Declares the stars table.
- Bootstrap DB → Schema: initializes · Bootstraps the database schema.
- Catalog UI → UI styles: styles with · Uses the custom CSS layer for the catalog UI.
- Catalog UI → Composer deps: loads deps · Runs with Composer-managed PHP dependencies.
- Sign-in → Local config: reads secrets · Uses local configuration for OAuth and service account settings.
- File proxy → Local config: reads secrets · Uses local configuration for Drive access credentials.
- Cache refresh → Local config: reads secrets · Uses local configuration for Drive crawling credentials.
- Admin dashboard → PDO access: reads data · Fetches dashboard data through the shared database connection.
