# shashwat-akhilesh-shukla/midnightreads architecture

> Architecture diagram of the GitHub repository shashwat-akhilesh-shukla/midnightreads, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shashwat-akhilesh-shukla/midnightreads
- Repository: https://github.com/shashwat-akhilesh-shukla/midnightreads

## Overview

##### Project Type and Purpose
- This is a full-stack web application called **Readverse**, a gamified book‐reading website.
- The **frontend** is a React single-page app (bootstrapped with Create React App) in the `public/` and `src/` folders.
- The **backend** is a Django project (`django_project/`) exposing REST endpoints for user authentication, PDF management, and progress tracking.

##### File Structure Analysis
- Top-level separation:
- `src/`, `public/` & `package.json` → React frontend
- `django_project/` → Django backend (with `readverse/` core settings and the `pdfs/` app)
- Frontend:
- `src/our_API.js` defines how React components call backend APIs.
- Components: `Browse.js`, `LoginSignup.js`, `PdfViewerModal.js`, etc., handle UI and data flow.
- Backend:
- `pdfs/` Django app contains `models.py`, `serializers.py`, `views.py`, and `urls.py` in `readverse/urls.py`.
- `uploads.py` suggests custom file‐upload handling.
- Migration files under `pdfs/migrations/` point to a relational database (e.g., PostgreSQL/SQLite).

##### Key README Insights
- The README title “Readverse” and tagline “A gamified book reading website” confirm the application’s goal.

##### Main Components
a. **Client (Web Browser)**
- Renders React SPA, manages user interactions (login, browsing, reading).
b. **Frontend Layer (React App)**
- UI Components (Navbar, Sidebar, Browse, PdfViewerModal)
- HTTP Client (`our_API.js`) calls backend REST endpoints.
c. **API Gateway / HTTP Server**
- (Optional) Nginx or Node / serve-static for hosting built React assets.
- Django’s WSGI/ASGI server handles API requests at `/api/...`.
d. **Backend Layer (Django Project)**
- **readverse/**: global settings, URL routing (`urls.py`), WSGI/ASGI entry points.
- **pdfs/** app:
– `models.py`: User, PDF metadata, progress tracking.
– `serializers.py`: JSON ↔ model translation.
– `views.py`: API views for login, signup, PDF list, PDF fetch.
– `uploads.py`: file storage logic (local or cloud).
e. **Database**
- Relational database (e.g., PostgreSQL) storing users, PDF metadata, reading status.
f. **File Storage**
- Local filesystem or cloud storage (e.g., S3) for PDF uploads.
g. **External Services** (if any)
- Authentication (JWT or session cookies)
- Analytics or gamification engine (if extended in future)

##### Relationships and Data Flow
- Browser → (HTTPS) → Frontend Server (static assets)
- React SPA → (REST) → Django API endpoints
- Django API → (ORM) → Database
- Django API → File Storage to fetch PDF binaries → returns to React
- React renders PDF in `PdfViewerModal.js` using fetched binary or URL

##### Architectural Patterns and Design Principles
- **Client-Server Separation**: Strict frontend/backend split, communicated over JSON REST.
- **Layered Architecture**: UI layer, service layer (views/serializers), data layer (models/ORM).
- **Modularization**: Django “pdfs” app encapsulates all PDF-related logic; React components are feature-oriented.
- **Stateless API**: Each request carries authentication and context; no server-side sessions.

##### Technologies and Frameworks
- Frontend: React, Create React App, CSS modules, JavaScript ES6+
- Backend: Python, Django, Django REST Framework (implied by serializers/views)
- Database: PostgreSQL or SQLite (Django migrations)
- File Storage: Local filesystem or AWS S3 via `uploads.py`
- Build Tools: npm, Webpack (via CRA), Django’s manage.py commands

##### Essential Elements
- Annotations for **port numbers** (e.g., 3000 for React dev, 8000 for Django)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client (Web Browser)"
        Browser["Web Browser"]:::external
    end

    subgraph "Frontend Layer (React App)"
        StaticShell["index.html"]:::frontend
        Package["package.json\npackage-lock.json"]:::frontend
        OurAPI["our_API.js"]:::frontend
        Browse["Browse.js"]:::frontend
        LoginSignup["LoginSignup.js"]:::frontend
        Signup["Signup.js"]:::frontend
        PdfViewer["PdfViewerModal.js"]:::frontend
        Navbar["Navbar.js"]:::frontend
        Sidebar["Sidebar.js"]:::frontend
        Footer["Footer.js"]:::frontend

        Browser -->|"loads SPA"| StaticShell
        StaticShell -->|"hydrates UI"| Browse
        Browse -->|"requests data"| OurAPI
        LoginSignup -->|"auth calls"| OurAPI
        Signup -->|"signup calls"| OurAPI
        PdfViewer -->|"fetch PDF"| OurAPI
        Navbar -->|"navigation UI"| Browse
        Sidebar -->|"navigation UI"| Browse
        Footer -->|"UI footer"| Browse
        OurAPI -->|"REST/HTTPS"| APIServer
    end

    subgraph "API Gateway / Static Server"
        Nginx["Nginx/CDN\n(serves static assets)"]:::external
        Nginx -->|"serves build"| StaticShell
    end

    subgraph "Backend Layer (Django)"
        APIServer["Django ASGI/WSGI\nServer (port 8000)"]:::backend
        Settings["settings.py"]:::backend
        URLs["urls.py"]:::backend
        ASGI["asgi.py"]:::backend
        WSGI["wsgi.py"]:::backend
        Manage["manage.py"]:::backend

        subgraph "pdfs App"
            Models["models.py"]:::backend
            Serializers["serializers.py"]:::backend
            Views["views.py"]:::backend
            LoginView["LoginView.py"]:::backend
            SignupView["Signupview.py"]:::backend
            Admin["admin.py"]:::backend
            Apps["apps.py"]:::backend
            Migrations["migrations/"]:::backend
        end

        Uploads["uploads.py"]:::backend

        APIServer --> Settings
        APIServer --> URLs
        APIServer --> ASGI
        APIServer --> WSGI
        APIServer --> Manage
        APIServer --> Models
        APIServer --> Serializers
        APIServer --> Views
        APIServer --> LoginView
        APIServer --> SignupView
        APIServer --> Admin
        APIServer --> Apps
        APIServer --> Migrations
        APIServer --> Uploads

        OurAPI -->|"GET/POST /api"| APIServer
    end

    subgraph "Data Layer"
        DB["Relational Database\n(PostgreSQL/SQLite)"]:::datastore
        FileStorage["File Storage\n(Local FS or S3)"]:::datastore

        Models -->|"ORM SQL"| DB
        Views -->|"CRUD metadata"| DB
        Views -->|"update progress"| DB
        Uploads -->|"store/fetch PDF"| FileStorage
        APIServer -->|"serve PDF"| FileStorage
        OurAPI -->|"download PDF"| FileStorage
    end

    classDef frontend fill:#e3f2fd,stroke:#2196f3,stroke-width:2px
    classDef backend fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    classDef datastore fill:#fff3e0,stroke:#ff9800,stroke-width:2px
    classDef external fill:#eeeeee,stroke:#9e9e9e,stroke-width:2px

    click OurAPI "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/src/our_API.js"
    click Browse "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/src/Browse.js"
    click LoginSignup "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/src/LoginSignup.js"
    click Signup "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/src/Signup.js"
    click PdfViewer "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/src/PdfViewerModal.js"
    click Navbar "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/src/Navbar.js"
    click Sidebar "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/src/Sidebar.js"
    click Footer "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/src/Footer.js"
    click StaticShell "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/public/index.html"
    click Package "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/package.json"
    click Settings "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/readverse/settings.py"
    click URLs "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/readverse/urls.py"
    click ASGI "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/readverse/asgi.py"
    click WSGI "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/readverse/wsgi.py"
    click Manage "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/manage.py"
    click Models "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/pdfs/models.py"
    click Serializers "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/pdfs/serializers.py"
    click Views "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/pdfs/views.py"
    click LoginView "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/pdfs/LoginView.py"
    click SignupView "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/pdfs/Signupview.py"
    click Admin "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/pdfs/admin.py"
    click Apps "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/pdfs/apps.py"
    click Migrations "https://github.com/shashwat-akhilesh-shukla/midnightreads/tree/main/django_project/pdfs/migrations/"
    click Uploads "https://github.com/shashwat-akhilesh-shukla/midnightreads/blob/main/django_project/uploads.py"
```
