# 1tony0/cps510 architecture

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

- Interactive diagram: https://gitdiagram.com/1tony0/cps510
- Repository: https://github.com/1tony0/cps510

## Overview

##### Project Type and Purpose
- This is a full-stack Ride & Pickup DBMS web application.
- It consists of a React (Vite) frontend, a Python Flask backend, and an Oracle relational database.
- The goal is to provide a UI for CRUD operations on Customers, Drivers, Vehicles, Locations, Rides, Payments, and Ratings, plus reporting.

##### File Structure Analysis
- Top-level directories:
- backend/  – Flask app (app.py, config.py, db.py), SQL scripts (init_db.sql), seeding (seed_data.py), requirements.
- frontend/ – Vite‐powered React app (index.html, src/, package.json, vite.config.js).
- Other artifacts: test_e2e.py for end-to-end tests.
- Configuration and environment management via .env and .env.example.
- Clear separation: backend handles API and data logic; frontend handles user interface and API calls.

##### Main Components
a. Frontend Layer
– React Components (CustomerList, RideForm, Reports, etc.)
– Axios service (frontend/src/services/api.js)
– Vite dev server / static hosting
b. Backend Layer
– Flask application (app.py) with RESTful routes under /api
– Business logic & query functions in db.py
– Configuration via config.py and python-dotenv
– CORS middleware
c. Database Layer
– Oracle Database instance with 7 BCNF tables (Customer, Driver, Vehicle, Location, Ride, Payment, Rating)
– Connection via cx_Oracle and connection pooling
d. Test & Dev Tools (optional)
– test_e2e.py interacting with REST API
– Virtual environment (venv) and npm environment

##### Relationships and Data Flows
- Frontend → Backend: HTTP/REST JSON calls (GET/POST/PUT/DELETE) on endpoints like /api/customers, /api/rides, /api/reports/*
- Backend → Database: SQL queries via cx_Oracle connector, returning result sets or executing DML
- Backend Configuration: Reads DB credentials and pool settings from .env
- Seed Data: seed_data.py or init_db.sql populates tables before runtime
- Dev Servers: Frontend on port 5173; Backend on port 5000

##### Architectural Patterns & Design Principles
- Three-Tier Architecture (Presentation, Application, Data)
- Layered separation:
- UI Layer: React components + client‐side routing
- Service Layer: Axios API wrapper
- API Layer: Flask routes + controllers
- Data Access Layer: db.py functions + SQL scripts
- Component-based design on frontend for maintainability
- RESTful API with consistent JSON envelope (success/data/message)
- BCNF database normalization to enforce data integrity

##### Essential Details to Capture
- Three-tier separation and communication protocols
- The role of environment config (.env) in connecting to DB
- The seed process and database initialization scripts
- The test script’s position in the overall flow
- The fact that the frontend and backend are independent services in development

## Diagram (Mermaid)

```mermaid
graph TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        ReactFront["React Frontend (5173)\nReact 19.2"]:::frontend
        ReactEntry["Entry Point\nmain.jsx"]:::frontend
        ReactRoot["Root Component\nApp.jsx"]:::frontend
        ReactComponents["UI Components\ncomponents/*.jsx"]:::frontend
        AxiosService["Axios Service\napi.js"]:::frontend
        ViteConfig["Vite Config\nvite.config.js"]:::frontend
        StaticHTML["Static HTML\nindex.html"]:::frontend

        ReactFront --> ReactEntry
        ReactEntry --> ReactRoot
        ReactRoot --> ReactComponents
        ReactRoot --> AxiosService
        ReactFront --> ViteConfig
        ReactFront --> StaticHTML
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        FlaskAPI["Flask API (5000)\nFlask 3.0"]:::backend
        Config["Config & Env\nconfig.py/.env"]:::backend
        DBLogic["Data Access\n db.py"]:::backend
        InitDB["Init Script\ninit_db.sql"]:::backend
        SeedData["Seed Script\nseed_data.py"]:::backend
        Requirements["Python Requirements\nrequirements.txt"]:::backend

        FlaskAPI --> Config
        FlaskAPI --> DBLogic
        DBLogic --> InitDB
        FlaskAPI --> SeedData
    end

    %% Database Layer
    OracleDB["Oracle DB\n7 BCNF Tables"]:::database

    %% Tools Layer
    subgraph "Dev & Test Tools"
        direction TB
        TestE2E["End-to-End Tests\ntest_e2e.py"]:::tools
    end

    %% Relationships
    ReactFront -->|"HTTP/REST JSON"| FlaskAPI
    FlaskAPI -->|"cx_Oracle / SQL"| OracleDB
    SeedData -->|"populates"| OracleDB
    TestE2E -->|"tests via HTTP"| FlaskAPI

    %% Click Events
    click ReactEntry "https://github.com/1tony0/cps510/blob/main/frontend/src/main.jsx"
    click ReactRoot "https://github.com/1tony0/cps510/blob/main/frontend/src/App.jsx"
    click ReactComponents "https://github.com/1tony0/cps510/tree/main/frontend/src/components"
    click AxiosService "https://github.com/1tony0/cps510/blob/main/frontend/src/services/api.js"
    click ViteConfig "https://github.com/1tony0/cps510/blob/main/frontend/vite.config.js"
    click StaticHTML "https://github.com/1tony0/cps510/blob/main/frontend/index.html"
    click FlaskAPI "https://github.com/1tony0/cps510/blob/main/backend/app.py"
    click Config "https://github.com/1tony0/cps510/blob/main/backend/config.py"
    click DBLogic "https://github.com/1tony0/cps510/blob/main/backend/db.py"
    click InitDB "https://github.com/1tony0/cps510/blob/main/backend/init_db.sql"
    click SeedData "https://github.com/1tony0/cps510/blob/main/backend/seed_data.py"
    click Requirements "https://github.com/1tony0/cps510/blob/main/backend/requirements.txt"
    click TestE2E "https://github.com/1tony0/cps510/blob/main/test_e2e.py"
    click README "https://github.com/1tony0/cps510/blob/main/README.md"

    %% Styles
    classDef frontend fill:#cdefff,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#d5f5e3,stroke:#229954,stroke-width:1px
    classDef database fill:#ffe0b2,stroke:#e67e22,stroke-width:1px
    classDef tools fill:#f0f0f0,stroke:#7f8c8d,stroke-width:1px
```
