# rhaeon66/blood_plus architecture

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

- Interactive diagram: https://gitdiagram.com/rhaeon66/blood_plus
- Repository: https://github.com/rhaeon66/blood_plus

## Overview

1. **Repository shape**
   - BloodPlus is a two-tier monorepo: a **Django REST API backend** in `backend/` and a **Next.js frontend** in `frontend/`.
   - The main architectural boundary is **client UI vs. server API**, connected over HTTP/JSON.

2. **Backend role**
   - `backend/config` holds the Django project configuration, URL routing, and WSGI entrypoint.
   - The backend exposes the domain through DRF APIs and uses **Simple JWT** for auth and **CORS** to allow the browser frontend to call it.

3. **Backend domain apps**
   - The backend is split into four Django apps, each representing a domain boundary:
     - `users` for authentication and user profile management
     - `locations` for location data
     - `donations` for donation lifecycle
     - `blood_requests` for blood request creation and tracking
   - Each app has its own `models.py`, `serializers.py`, `views.py`, `urls.py`, and migrations, so the API is organized by domain rather than by a single monolith.

4. **User/auth subsystem**
   - `users` is the identity and profile subsystem.
   - It includes a custom user model/managers, JWT-related serializers/views, a `stats.py` module for user metrics, and management commands such as `create_superuser` and `populate_data`.
   - This app is the primary source of authenticated identity used by donations and blood request records.

5. **Donation subsystem**
   - `donations` models donation records and their status workflow.
   - The migrations show status evolution and an `approved_at` timestamp, which implies a donation approval/review process.
   - This app likely feeds the profile page’s donation history and donation statistics.

6. **Blood request subsystem**
   - `blood_requests` handles requests for blood, including creation and detail retrieval.
   - The app has separate serializers, views, and URL routes, indicating it is exposed as its own REST resource.
   - The frontend’s request form and blood-request listing/detail pages map directly to this backend domain.

7. **Location/data subsystem**
   - `locations` is a supporting domain for geographic data used by requests, donors, or profile filtering.
   - The repo also includes a Bangladesh upazila JSON dataset in the frontend tree, which likely backs location selectors or seeded data.
   - This suggests location data is treated as reference data rather than a standalone user-facing feature.

8. **Persistence and data model**
   - The backend uses **SQLite** in development (`backend/db.sqlite3` per README) and Django migrations are the schema source of truth.
   - The ORM is the main persistence layer; there is no separate service or database boundary in the repo.

9. **Frontend role**
   - The frontend uses **Next.js App Router** under `frontend/app/` with route-based pages for:
     - home, about
     - auth sign-in/register
     - blood requests list/detail
     - request-blood form
     - profile
   - This is a server-renderable React app, but the architecture is effectively a browser client for the Django API.

10. **Frontend component structure**
    - UI is decomposed into feature components under `frontend/components/`:
      - homepage sections
      - shared layout (`Navbar`, `Footer`)
      - profile widgets and modals
      - request-blood form and sign-in prompt
    - This indicates the frontend is organized by page/feature composition rather than a shared design-system-only approach.

11. **Client state and API access**
    - `frontend/lib/api.js` centralizes HTTP calls, and `frontend/lib/authStore.js` uses **Zustand** for client-side auth state.
    - This is likely where JWT tokens/session state are stored and attached to API requests.
    - The frontend depends on **Axios** for request transport and on the backend’s JWT endpoints for sign-in/register flows.

12. **Operational flow**
    - Typical request flow is:
      1. User interacts with a Next.js page
      2. UI component calls the API layer
      3. Django REST endpoint validates the request and JWT/auth context
      4. Django ORM reads/writes SQLite through the domain app model
      5. JSON response returns to the frontend for rendering
    - CORS is the key deployment/runtime bridge that makes this browser-to-API flow work.

13. **Repo tooling and environment**
    - Both sides include `.env.example` files, implying environment-specific configuration for API URLs, auth settings, and similar runtime values.
    - Styling is handled with **Tailwind CSS**, and lint/build tooling is configured on the frontend.
    - The backend includes standard Django management commands and migration-based schema management, which are important for diagramming the deployment/setup path.

Main entry points: [`frontend/app`](https://github.com/rhaeon66/blood_plus/tree/master/frontend/app) (App Router), [`backend/config`](https://github.com/rhaeon66/blood_plus/tree/master/backend/config) (Django config), [`backend/apps/users`](https://github.com/rhaeon66/blood_plus/tree/master/backend/apps/users) (Users), [`backend/apps/blood_requests`](https://github.com/rhaeon66/blood_plus/tree/master/backend/apps/blood_requests) (Blood requests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App Router<br/>nextjs routes"]
  node_frontend_homepage_components["Home UI<br/>feature components"]
  node_frontend_layout_components["Layout<br/>shared chrome"]
  node_frontend_profile_components["Profile UI<br/>profile widgets"]
  node_frontend_request_components["Request UI<br/>request form"]
  node_frontend_api["API client<br/>http layer<br/>[api.js]"]
  node_frontend_auth_store["Auth state<br/>zustand store<br/>[authStore.js]"]
end

subgraph group_backend["Backend"]
  node_backend_config["Django config<br/>project config"]
  node_backend_users["Users<br/>identity app"]
  node_backend_locations["Locations<br/>reference app"]
  node_backend_donations["Donations<br/>workflow app"]
  node_backend_requests["Blood requests<br/>request app"]
  node_backend_orm[("ORM storage<br/>persistence")]
end

node_frontend_app -->|"renders"| node_frontend_homepage_components
node_frontend_app -->|"wraps"| node_frontend_layout_components
node_frontend_app -->|"renders"| node_frontend_profile_components
node_frontend_app -->|"renders"| node_frontend_request_components
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_auth_store -->|"auth headers"| node_frontend_api
node_frontend_request_components -->|"reads auth"| node_frontend_auth_store
node_frontend_api -->|"HTTP/JSON"| node_backend_config
node_backend_config -->|"routes"| node_backend_users
node_backend_config -->|"routes"| node_backend_locations
node_backend_config -->|"routes"| node_backend_donations
node_backend_config -->|"routes"| node_backend_requests
node_backend_users -->|"persists"| node_backend_orm
node_backend_locations -->|"persists"| node_backend_orm
node_backend_donations -->|"persists"| node_backend_orm
node_backend_requests -->|"persists"| node_backend_orm
node_backend_users -->|"authorizes"| node_backend_donations
node_backend_users -->|"authorizes"| node_backend_requests
node_backend_locations -->|"supports"| node_backend_requests

click node_frontend_app "https://github.com/rhaeon66/blood_plus/tree/master/frontend/app"
click node_frontend_homepage_components "https://github.com/rhaeon66/blood_plus/tree/master/frontend/components/homepage"
click node_frontend_layout_components "https://github.com/rhaeon66/blood_plus/tree/master/frontend/components/layout"
click node_frontend_profile_components "https://github.com/rhaeon66/blood_plus/tree/master/frontend/components/profile"
click node_frontend_request_components "https://github.com/rhaeon66/blood_plus/tree/master/frontend/components/request-blood-page"
click node_frontend_api "https://github.com/rhaeon66/blood_plus/blob/master/frontend/lib/api.js"
click node_frontend_auth_store "https://github.com/rhaeon66/blood_plus/blob/master/frontend/lib/authStore.js"
click node_backend_config "https://github.com/rhaeon66/blood_plus/tree/master/backend/config"
click node_backend_users "https://github.com/rhaeon66/blood_plus/tree/master/backend/apps/users"
click node_backend_locations "https://github.com/rhaeon66/blood_plus/tree/master/backend/apps/locations"
click node_backend_donations "https://github.com/rhaeon66/blood_plus/tree/master/backend/apps/donations"
click node_backend_requests "https://github.com/rhaeon66/blood_plus/tree/master/backend/apps/blood_requests"

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_frontend_app,node_frontend_homepage_components,node_frontend_layout_components,node_frontend_profile_components,node_frontend_request_components,node_frontend_api,node_frontend_auth_store toneBlue
class node_backend_config,node_backend_users,node_backend_locations,node_backend_donations,node_backend_requests,node_backend_orm toneAmber
```

## Components

### Frontend

Next.js client app and UI composition

- [App Router](https://github.com/rhaeon66/blood_plus/tree/master/frontend/app): nextjs routes · Route-based pages for home, auth, blood requests, profile, and request forms · `frontend/app`
- [Home UI](https://github.com/rhaeon66/blood_plus/tree/master/frontend/components/homepage): feature components · Landing-page sections composed into the home experience · `frontend/components/homepage`
- [Layout](https://github.com/rhaeon66/blood_plus/tree/master/frontend/components/layout): shared chrome · Global navigation and footer shared across pages · `frontend/components/layout`
- [Profile UI](https://github.com/rhaeon66/blood_plus/tree/master/frontend/components/profile): profile widgets · Donation history, stats, personal info, and profile editing flows · `frontend/components/profile`
- [Request UI](https://github.com/rhaeon66/blood_plus/tree/master/frontend/components/request-blood-page): request form · Blood request form and sign-in prompt used by the request flow · `frontend/components/request-blood-page`
- [API client](https://github.com/rhaeon66/blood_plus/blob/master/frontend/lib/api.js): http layer · Centralized Axios-based client for backend calls · `frontend/lib/api.js`
- [Auth state](https://github.com/rhaeon66/blood_plus/blob/master/frontend/lib/authStore.js): zustand store · Client-side JWT/session state used by authenticated pages · `frontend/lib/authStore.js`

### Backend

Django REST API, domain apps, and persistence

- [Django config](https://github.com/rhaeon66/blood_plus/tree/master/backend/config): project config · Settings, URL routing, and WSGI entrypoint for the API · `backend/config`
- [Users](https://github.com/rhaeon66/blood_plus/tree/master/backend/apps/users): identity app · Custom user model, JWT serializers/views, metrics, and management commands · `backend/apps/users`
- [Locations](https://github.com/rhaeon66/blood_plus/tree/master/backend/apps/locations): reference app · Geographic reference data exposed through REST endpoints · `backend/apps/locations`
- [Donations](https://github.com/rhaeon66/blood_plus/tree/master/backend/apps/donations): workflow app · Donation records and approval/status lifecycle · `backend/apps/donations`
- [Blood requests](https://github.com/rhaeon66/blood_plus/tree/master/backend/apps/blood_requests): request app · Blood request creation, listing, and detail retrieval · `backend/apps/blood_requests`
- **ORM storage**: persistence · Django ORM and migration-managed SQLite-backed data storage

## Connections

- App Router → Home UI: renders · Home page is assembled from homepage sections
- App Router → Layout: wraps · All routes share global navigation and footer
- App Router → Profile UI: renders · Profile route composes donation and personal-info sections
- App Router → Request UI: renders · Request-blood route uses the form and sign-in prompt
- App Router → API client: calls · Pages delegate backend interaction to the API client
- Auth state → API client: auth headers · Stored auth state is used when making API requests
- Request UI → Auth state: reads auth · Request flow checks sign-in state before submission
- API client → Django config: HTTP/JSON · Browser requests are routed to the Django API
- Django config → Users: routes · Project routing exposes the users domain endpoints
- Django config → Locations: routes · Project routing exposes location endpoints
- Django config → Donations: routes · Project routing exposes donation endpoints
- Django config → Blood requests: routes · Project routing exposes blood request endpoints
- Users → ORM storage: persists · Users, profiles, and JWT identity data are stored through the ORM
- Locations → ORM storage: persists · Reference location data is loaded and queried from the database
- Donations → ORM storage: persists · Donation lifecycle records are stored via migrations and ORM models
- Blood requests → ORM storage: persists · Blood request records are stored via migrations and ORM models
- Users → Donations: authorizes · Donation records are tied to authenticated users
- Users → Blood requests: authorizes · Request creation and ownership depend on user identity
- Locations → Blood requests: supports · Locations feed request targeting and filtering