# shanglin-wu/database-system-final-project architecture

> Architecture diagram of the GitHub repository shanglin-wu/database-system-final-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shanglin-wu/database-system-final-project
- Repository: https://github.com/shanglin-wu/database-system-final-project

## Overview

##### Project type and purpose
- This is an iOS mobile-client application written in Swift that displays restaurant data.
- It fetches data from remote RESTful APIs (“getRestaurant”, “getRestaurantList”) backed by a MongoDB database, decodes JSON responses, caches or persists data locally (via Realm), and presents it in table views with image loading (SDWebImage), star ratings (Cosmos) and toast notifications (Toast).

##### File structure
- Top-level Xcode artifacts: DatabaseSystemProject.xcodeproj, DatabaseSystemProject.xcworkspace
- Core source folders under DatabaseSystemProject/:
- Api/… holds request/response model definitions
- ApiAgent/ApiAgent.swift encapsulates network calls
- JSONDecoder/JSONDecoder.swift is a custom JSON parsing helper
- DataManager/DataManager.swift orchestrates business logic (fetching, decoding, caching)
- View controllers and storyboard files under Base.lproj and .swift files (ContentViewController, RestaurantDetailViewController, etc.)
- Custom UITableViewCell implementations (restaurantResultTableViewCell, reviewTableViewCell)
- Third-party frameworks integrated via CocoaPods:
- Realm & RealmSwift for local persistence
- SDWebImage for asynchronous image downloading/caching
- Cosmos for rating UI
- Toast for in-app notifications

##### README
- Confirms the use of Swift and MongoDB as the remote data store.

##### Main components & interactions
a. Mobile Application (iOS)
– Presentation Layer: Storyboard/Swift UI classes (ViewControllers, custom Cells)
– Service Layer: DataManager (business logic), ApiAgent (network client), JSONDecoder (parsing)
– Persistence Layer: Realm (local DB/cache)
– Utilities & Third-Party Modules: SDWebImage, Cosmos, Toast
b. Remote Backend API Service
– REST endpoints: /getRestaurantList, /getRestaurant
– JSON over HTTPS
c. Remote Database
– MongoDB holds the authoritative restaurant data

Data flow:
ViewController → DataManager
DataManager → ApiAgent → Network request → Backend Service → MongoDB
Response JSON → ApiAgent → JSONDecoder → Swift models → DataManager
DataManager → (optional) Realm persistence → returns model(s) → ViewController
ViewController → Cell rendering → SDWebImage & Cosmos → UI display
ViewController → Toast → user notifications

##### Architectural patterns & design principles
- Layered architecture separating Presentation, Service, Persistence
- Single Responsibility: ApiAgent only does networking; JSONDecoder only decodes; DataManager orchestrates
- Dependency inversion: Controllers depend on DataManager protocol, not concrete networking details
- Offline caching: Realm used to persist or cache API responses for offline/fast retrieval

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Mobile App Layers
    subgraph "Mobile App" 
        direction TB
        subgraph "Presentation Layer" 
            direction TB
            ContentVC["ContentViewController"]:::presentation
            ListVC["Restaurant List ViewController"]:::presentation
            DetailVC["Restaurant Detail ViewController"]:::presentation
            SavedVC["Saved Restaurants Controller"]:::presentation
            RestCell["RestaurantResultTableViewCell"]:::presentation
            RevCell["ReviewTableViewCell"]:::presentation
            Storyboards["Storyboards"]:::presentation
        end

        subgraph "Service Layer"
            direction TB
            DataMgr["DataManager"]:::service
            ApiAgent["ApiAgent"]:::service
            JSONDec["JSONDecoder"]:::service
        end

        subgraph "Persistence Layer"
            direction TB
            RealmDB["Realm"]:::persistence
        end

        subgraph "Third-Party Libraries"
            direction TB
            SDWebImg["SDWebImage"]:::thirdparty
            CosmosLib["Cosmos"]:::thirdparty
            ToastLib["Toast"]:::thirdparty
        end
    end

    %% External Services
    NetworkCloud(["Internet (HTTPS)"]):::external
    BackendAPI["Backend API Service"]:::external
    MongoDB[(MongoDB)]:::database

    %% Data Flow Arrows
    ContentVC -->|uses| DataMgr
    ListVC -->|uses| DataMgr
    DetailVC -->|uses| DataMgr
    SavedVC -->|uses| DataMgr

    DataMgr -->|1: fetch| ApiAgent
    ApiAgent -->|JSON over HTTPS| NetworkCloud
    NetworkCloud -->|REST endpoints| BackendAPI
    BackendAPI -->|query| MongoDB
    MongoDB -->|JSON response| BackendAPI
    BackendAPI -->|JSON| NetworkCloud
    NetworkCloud -->|JSON| ApiAgent
    ApiAgent -->|parse| JSONDec
    JSONDec -->|models| DataMgr

    DataMgr -->|cache| RealmDB
    RealmDB -->|read| DataMgr
    DataMgr -->|models| ContentVC
    DataMgr -->|models| ListVC
    DataMgr -->|models| DetailVC
    DataMgr -->|models| SavedVC

    ListVC -->|renders| RestCell
    DetailVC -->|renders| RevCell
    RestCell -->|load image| SDWebImg
    DetailVC -->|display rating| CosmosLib
    ContentVC -->|notify| ToastLib

    %% Click Events
    click ContentVC "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/ContentViewController.swift"
    click ListVC "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/ViewController.swift"
    click DetailVC "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/RestaurantDetailViewController.swift"
    click SavedVC "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/saveRestaurantTableViewController.swift"
    click RestCell "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/restaurantResultTableViewCell/restaurantResultTableViewCell.swift"
    click RevCell "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/reviewTableViewCell/reviewTableViewCell.swift"
    click Storyboards "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/Base.lproj/Main.storyboard"
    %% Assuming both storyboards live in same dir
    click DataMgr "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/DataManager/DataManager.swift"
    click ApiAgent "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/ApiAgent/ApiAgent.swift"
    click JSONDec "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/JSONDecoder/JSONDecoder.swift"
    click getResReq "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/Api/getRestaurant/getRestaurantReq.swift"
    click getResRes "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/Api/getRestaurant/getRestaurantRes.swift"
    click getListReq "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/Api/getRestaurantList/getRestaurantListReq.swift"
    click getListRes "https://github.com/shanglin-wu/database-system-final-project/blob/master/DatabaseSystemProject/Api/getRestaurantList/getRestaurantListRes.swift"
    click RealmDB "https://github.com/shanglin-wu/database-system-final-project/tree/master/Pods/Realm"
    click RealmDB "https://github.com/shanglin-wu/database-system-final-project/tree/master/Pods/RealmSwift"
    click SDWebImg "https://github.com/shanglin-wu/database-system-final-project/tree/master/Pods/SDWebImage"
    click CosmosLib "https://github.com/shanglin-wu/database-system-final-project/tree/master/Pods/Cosmos"
    click ToastLib "https://github.com/shanglin-wu/database-system-final-project/tree/master/Pods/Toast"

    %% Styles
    classDef presentation fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef service fill:#DFF5D0,stroke:#228B22,color:#228B22
    classDef persistence fill:#F0E68C,stroke:#DAA520,color:#DAA520
    classDef thirdparty fill:#FFE4B5,stroke:#FF8C00,color:#FF8C00
    classDef external fill:#E8E8E8,stroke:#808080,color:#808080
    classDef database fill:#E8F4FF,stroke:#1E90FF,color:#1E90FF
```
