# rajukarki/react-django-portal architecture

> Architecture diagram of the GitHub repository rajukarki/react-django-portal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rajukarki/react-django-portal
- Repository: https://github.com/rajukarki/react-django-portal

## Overview

##### What this project is (type + purpose)
This is a **full-stack “portal” starter**:
- **Backend**: Django + Django REST Framework (DRF) exposing an **auth-centric REST API**.
- **Auth mechanism**: **JWT** via **SimpleJWT** with **refresh tokens** and **blacklisting** for logout.
- **Frontend**: React (Vite) SPA using **React Router** and **Axios interceptors**.
- Primary use case: **register/login**, store tokens client-side, **protect routes** on both FE + BE, and demonstrate a protected **Dashboard**.

- Browser SPA ↔ REST API over HTTP
- JWT access/refresh lifecycle (attach Bearer token; refresh on expiry; blacklist on logout)
- CORS/dev-server separation
- Persistence (SQLite + Django auth tables + token blacklist tables)

##### Read the structure as architecture boundaries
From the tree:

##### Backend boundary (`backend/`)
- `backend/core/` is the **Django project**: settings, URL routing, ASGI/WSGI entrypoints.
- `backend/accounts/` is the **domain app** for authentication APIs:
- `models.py` (likely leveraging Django User or extensions)
- `serializers.py` (DRF serialization / validation)
- `views.py` (register/login/logout/dashboard endpoints)
- `urls.py` (mounts app routes under `/api/v1/user/`)
- `utils.py` (support logic—often token helpers, etc.)
- `requirements.txt` indicates key dependencies: DRF, SimpleJWT, blacklist app, cors headers, decouple, etc.
- DB: README implies `db.sqlite3` exists (dev persistence).

##### Frontend boundary (`frontend/`)
- Vite app with:
- `src/App.jsx` (route table)
- `AuthProvider.jsx` (auth state derived from tokens in `localStorage`)
- `AxiosInstance.js` (base URL from `VITE_BACKEND_BASE_API`, injects Bearer token, refresh flow)
- `PrivateRoute.jsx` / `PublicRoute.jsx` (route guards)
- UI components: `Login`, `Register`, `Dashboard`, layout bits.

##### React SPA (Vite build)
- Router layer (React Router)
- Auth state layer (`AuthProvider`)
- Route guards (`PrivateRoute`, `PublicRoute`)
- HTTP client layer (`AxiosInstance` w/ interceptors)
##### Storage
- `localStorage`: `accessToken`, `refreshToken` (per README behavior)

##### Django entrypoints
- WSGI/ASGI (deployment boundary)
##### Django URL routing
- `core/urls.py` mounts `/api/v1/user/…`
- `accounts/urls.py` defines endpoints
##### Accounts app (DRF layer)
- Views (controllers)
- Serializers (validation + shaping payloads)
- Permissions (`IsAuthenticated` for dashboard)
##### Auth/token subsystem
- SimpleJWT: issue access/refresh
- Refresh endpoint: mints new access token
- Blacklist app: stores revoked refresh tokens (logout)
##### Database
- SQLite (dev)
- Data sets: `auth_user`, token blacklist tables, etc.

##### Environment configuration
- Backend `.env` via `python-decouple` (`SECRET_KEY`, `DEBUG`)
- Frontend `.env` via Vite (`VITE_BACKEND_BASE_API`)

##### Registration flow
- SPA `Register.jsx` → `AxiosInstance` → `POST /api/v1/user/register/`
- Backend `accounts.views` → `accounts.serializers` → create `User` → persist in DB
- Response back to SPA (success/failure)

##### Login flow (token issuance)
- SPA `Login.jsx` → `POST /api/v1/user/login/`
- Backend authenticates credentials
- Backend returns `{ access, refresh }`
- SPA stores tokens in `localStorage`
- SPA updates auth state (`AuthProvider`)

##### Authenticated request flow (Bearer token)
- SPA → `GET /api/v1/user/dashboard/`
- Axios interceptor attaches `Authorization: Bearer <access>`
- Backend DRF permission `IsAuthenticated` validates JWT
- Backend returns dashboard payload

##### Access token expiry → refresh-token flow
- SPA calls protected endpoint → receives 401 (expired access)
- Axios interceptor triggers refresh:
- `POST /api/v1/user/token/refresh/` (or your custom path, but README lists SimpleJWT route)
- Backend validates refresh token → returns new access
- SPA updates `localStorage` and retries original request

##### Logout flow (blacklist)
- SPA → `POST /api/v1/user/logout/` with refresh token
- Backend blacklists refresh token in DB
- SPA clears tokens from `localStorage`

##### Architectural patterns worth highlighting (specific to this repo)
- **SPA + REST API** separation (two deployables, two dev servers).
- **Token-based stateless auth** (access token) + **stateful revocation** (refresh token blacklist).
- **Layered backend**: URLs → Views → Serializers → DB.
- **Client-side cross-cutting concern**: Axios interceptors centralize auth headers + refresh retries.
- **Dual protection**:
- Frontend: `PrivateRoute`/`PublicRoute`
- Backend: DRF permissions for protected endpoints

- Browser (React SPA)
- Django REST API
- SQLite DB
- (Optional) “Token Blacklist tables” as a labeled part of DB
- SPA → API (HTTP JSON)
- API ↔ DB (ORM)
Annotations:
- JWT Bearer auth
- CORS allowed origin (dev)

Participants:
- User
- React UI (Login/Register/Dashboard)
- AxiosInstance (interceptor)
- Django API (accounts + SimpleJWT)
- DB
Sequences for login, dashboard call, refresh, logout.

##### Frontend labels
- “Routing”: `frontend/src/App.jsx`
- “Auth state”: `frontend/src/AuthProvider.jsx`
- “Route guards”: `frontend/src/PrivateRoute.jsx`, `frontend/src/PublicRoute.jsx`
- “HTTP client + refresh”: `frontend/src/AxiosInstance.js`
- “Screens”: `frontend/src/components/Login.jsx`, `Register.jsx`, `dashboard/Dashboard.jsx`

##### Backend labels
- “Project config”: `backend/core/settings.py`
- “API routing”: `backend/core/urls.py`, `backend/accounts/urls.py`
- “Auth API”: `backend/accounts/views.py`, `serializers.py`
- “Data model”: `backend/accounts/models.py` (and Django User)
- “Token system”: SimpleJWT + blacklist (dependency; configured in settings)

Elements explicitly:
- Blue rectangles: frontend components
- Green rectangles: backend components
- Red note/annotation: “401 triggers refresh flow”
- **Trust boundaries**:
- Browser boundary (untrusted client)
- Server boundary (trusted)
- Storage boundary (localStorage is client-controlled)

##### “Don’t overthink it” decomposition checklist (capture as many components as possible)
- React Router
- AuthProvider (isLoggedIn)
- localStorage tokens
- Axios interceptors (attach token + refresh)
- Django URL routing (core → accounts)
- DRF views/serializers
- DRF permission on dashboard
- SimpleJWT token issue + refresh
- Token blacklist on logout
- SQLite persistence
- Env vars on both sides
- CORS

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% High-level Container View
    %% =========================
    subgraph "Client (Untrusted Boundary)"
        U["User"]:::external

        subgraph "Browser"
            SPA["React SPA (Vite)"]:::frontend
            LS[("localStorage\naccessToken + refreshToken")]:::storage
        end

        subgraph "Frontend Internals"
            FE_Router["React Router\n(Route table)"]:::frontend
            FE_Auth["AuthProvider\n(token-derived auth state)"]:::frontend
            FE_GuardPriv["PrivateRoute\n(protected routes)"]:::frontend
            FE_GuardPub["PublicRoute\n(public-only routes)"]:::frontend
            FE_Axios["AxiosInstance\n(interceptors: Bearer + refresh)"]:::frontend

            FE_Login["Login Screen"]:::frontend
            FE_Register["Register Screen"]:::frontend
            FE_Dashboard["Dashboard Screen\n(Protected)"]:::frontend

            FE_Main["App Bootstrap"]:::frontend
            FE_Vite["Vite Config + Env Wiring\n(VITE_BACKEND_BASE_API)"]:::config
            FE_Pkg["Frontend Deps\n(React Router, Axios, etc.)"]:::config
        end
    end

    subgraph "Network / Integration"
        HTTP["HTTP(S) JSON"]:::integration
        CORS["CORS Policy\n(allow dev origin http://localhost:5173)"]:::integration
        Note401["NOTE: 401 triggers refresh\nthen retry original request"]:::note
    end

    subgraph "Server (Trusted Boundary)"
        subgraph "Django Backend"
            DJ_Manage["manage.py\n(Management Entrypoint)"]:::backend
            DJ_ASGI["ASGI Entrypoint"]:::backend
            DJ_WSGI["WSGI Entrypoint"]:::backend

            DJ_Settings["core settings\n(SimpleJWT, CORS, env via decouple)"]:::backend
            DJ_RootUrls["core URL routing\n(mounts /api/v1/user/...)"]:::backend

            subgraph "accounts app (Auth APIs)"
                ACC_Urls["accounts URLs\n(/api/v1/user/*)"]:::backend
                ACC_Views["DRF Views\n(register/login/logout/dashboard)"]:::backend
                ACC_Ser["DRF Serializers\n(validation + shaping)"]:::backend
                ACC_Models["Models\n(User + related)"]:::backend
                ACC_Utils["Utils\n(token helpers)"]:::backend

                ACC_Perm["DRF Permission\nIsAuthenticated (dashboard)"]:::security
                JWT_Issue["SimpleJWT\nIssue access+refresh"]:::security
                JWT_Refresh["SimpleJWT\nRefresh access token"]:::security
                JWT_Blacklist["Blacklist App\n(revoke refresh on logout)"]:::security
            end

            REQ["Backend Dependencies\n(DRF, SimpleJWT, CORS, etc.)"]:::config
        end

        DB[("SQLite DB\n(auth_user + token_blacklist tables)")]:::database
    end

    %% =========================
    %% Frontend Wiring
    %% =========================
    U -->|"uses"| SPA
    FE_Main -->|"bootstraps"| SPA
    SPA -->|"routes"| FE_Router
    FE_Router -->|"public-only"| FE_GuardPub
    FE_Router -->|"protected"| FE_GuardPriv
    FE_GuardPriv -->|"reads auth state"| FE_Auth
    FE_GuardPub -->|"reads auth state"| FE_Auth

    FE_Auth <-->|"load/save tokens"| LS
    FE_Axios <-->|"read/write tokens"| LS

    FE_Router -->|"renders"| FE_Login
    FE_Router -->|"renders"| FE_Register
    FE_Router -->|"renders"| FE_Dashboard

    %% =========================
    %% Network + CORS
    %% =========================
    SPA -->|"API calls"| HTTP
    HTTP -->|"enforced by"| CORS
    CORS -->|"permits requests to"| DJ_Settings

    %% =========================
    %% Backend Wiring
    %% =========================
    DJ_ASGI -->|"serves"| DJ_RootUrls
    DJ_WSGI -->|"serves"| DJ_RootUrls
    DJ_RootUrls -->|"mounts /api/v1/user/..."| ACC_Urls
    ACC_Urls -->|"dispatches"| ACC_Views
    ACC_Views -->|"validate/shape"| ACC_Ser
    ACC_Views -->|"use helpers"| ACC_Utils
    ACC_Ser -->|"persist/load"| ACC_Models
    ACC_Models -->|"ORM"| DB

    DJ_Settings -->|"configures"| JWT_Issue
    DJ_Settings -->|"configures"| JWT_Refresh
    DJ_Settings -->|"enables"| JWT_Blacklist
    DJ_Settings -->|"uses"| REQ

    %% =========================
    %% Core Auth Flows (A-E)
    %% =========================

    %% A) Registration
    FE_Register -->|"POST /api/v1/user/register/"| FE_Axios
    FE_Axios -->|"HTTP JSON"| HTTP -->|"POST /api/v1/user/register/"| ACC_Views
    ACC_Views -->|"create user"| ACC_Ser -->|"save"| ACC_Models -->|"insert"| DB
    ACC_Views -->|"response (success/failure)"| HTTP -->|"HTTP response"| FE_Axios -->|"show result"| FE_Register

    %% B) Login (issue tokens)
    FE_Login -->|"POST /api/v1/user/login/"| FE_Axios
    FE_Axios -->|"HTTP JSON"| HTTP -->|"POST /api/v1/user/login/"| ACC_Views
    ACC_Views -->|"authenticate"| ACC_Ser
    ACC_Views -->|"issue {access,refresh}"| JWT_Issue
    JWT_Issue -->|"tokens"| ACC_Views
    ACC_Views -->|"return tokens"| HTTP -->|"200 {access,refresh}"| FE_Axios
    FE_Axios -->|"store tokens"| LS
    LS -->|"notifies via state update"| FE_Auth

    %% C) Authenticated request (Bearer token)
    FE_Dashboard -->|"GET /api/v1/user/dashboard/"| FE_Axios
    FE_Axios -->|"attach Authorization: Bearer <access>"| HTTP -->|"GET /api/v1/user/dashboard/"| ACC_Views
    ACC_Views -->|"enforce"| ACC_Perm
    ACC_Perm -->|"validate JWT"| JWT_Issue
    ACC_Views -->|"fetch/compute payload"| ACC_Models -->|"select"| DB
    ACC_Views -->|"dashboard payload"| HTTP -->|"200 JSON"| FE_Axios -->|"render"| FE_Dashboard

    %% D) Access expiry -> refresh -> retry
    HTTP -->|"401 (expired access)"| FE_Axios
    FE_Axios -.->|"trigger refresh"| Note401
    FE_Axios -.->|"POST /api/v1/user/token/refresh/"| HTTP -.->|"POST /api/v1/user/token/refresh/"| JWT_Refresh
    JWT_Refresh -.->|"validate refresh token"| DB
    JWT_Refresh -.->|"new access"| HTTP -.->|"200 {access}"| FE_Axios
    FE_Axios -.->|"update access token"| LS
    FE_Axios -.->|"retry original request"| HTTP

    %% E) Logout (blacklist refresh)
    SPA -->|"logout action"| FE_Axios
    FE_Axios -->|"POST /api/v1/user/logout/ (refresh)"| HTTP -->|"POST /api/v1/user/logout/"| ACC_Views
    ACC_Views -->|"blacklist refresh"| JWT_Blacklist -->|"store revoked token"| DB
    ACC_Views -->|"200 logged out"| HTTP -->|"response"| FE_Axios
    FE_Axios -->|"clear tokens"| LS
    LS -->|"auth state becomes logged-out"| FE_Auth

    %% =========================
    %% Click Events (from mapping)
    %% =========================
    click DJ_Settings "https://github.com/rajukarki/react-django-portal/blob/main/backend/core/settings.py"
    click DJ_RootUrls "https://github.com/rajukarki/react-django-portal/blob/main/backend/core/urls.py"
    click DJ_ASGI "https://github.com/rajukarki/react-django-portal/blob/main/backend/core/asgi.py"
    click DJ_WSGI "https://github.com/rajukarki/react-django-portal/blob/main/backend/core/wsgi.py"
    click DJ_Manage "https://github.com/rajukarki/react-django-portal/blob/main/backend/manage.py"
    click ACC_Models "https://github.com/rajukarki/react-django-portal/blob/main/backend/accounts/models.py"
    click ACC_Ser "https://github.com/rajukarki/react-django-portal/blob/main/backend/accounts/serializers.py"
    click ACC_Views "https://github.com/rajukarki/react-django-portal/blob/main/backend/accounts/views.py"
    click ACC_Urls "https://github.com/rajukarki/react-django-portal/blob/main/backend/accounts/urls.py"
    click ACC_Utils "https://github.com/rajukarki/react-django-portal/blob/main/backend/accounts/utils.py"
    click REQ "https://github.com/rajukarki/react-django-portal/blob/main/backend/requirements.txt"
    click FE_Router "https://github.com/rajukarki/react-django-portal/blob/main/frontend/src/App.jsx"
    click FE_Auth "https://github.com/rajukarki/react-django-portal/blob/main/frontend/src/AuthProvider.jsx"
    click FE_Axios "https://github.com/rajukarki/react-django-portal/blob/main/frontend/src/AxiosInstance.js"
    click FE_GuardPriv "https://github.com/rajukarki/react-django-portal/blob/main/frontend/src/PrivateRoute.jsx"
    click FE_GuardPub "https://github.com/rajukarki/react-django-portal/blob/main/frontend/src/PublicRoute.jsx"
    click FE_Login "https://github.com/rajukarki/react-django-portal/blob/main/frontend/src/components/Login.jsx"
    click FE_Register "https://github.com/rajukarki/react-django-portal/blob/main/frontend/src/components/Register.jsx"
    click FE_Dashboard "https://github.com/rajukarki/react-django-portal/blob/main/frontend/src/components/dashboard/Dashboard.jsx"
    click FE_Main "https://github.com/rajukarki/react-django-portal/blob/main/frontend/src/main.jsx"
    click FE_Vite "https://github.com/rajukarki/react-django-portal/blob/main/frontend/vite.config.js"
    click FE_Pkg "https://github.com/rajukarki/react-django-portal/blob/main/frontend/package.json"
    click SPA "https://github.com/rajukarki/react-django-portal/tree/main/frontend/"
    click DJ_Settings "https://github.com/rajukarki/react-django-portal/blob/main/backend/core/settings.py"
    click ACC_Urls "https://github.com/rajukarki/react-django-portal/blob/main/backend/accounts/urls.py"

    %% =========================
    %% Styles (Color + Shapes)
    %% =========================
    classDef external fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:1px
    classDef frontend fill:#dbeafe,stroke:#1d4ed8,color:#0f172a,stroke-width:1px
    classDef backend fill:#dcfce7,stroke:#166534,color:#052e16,stroke-width:1px
    classDef database fill:#fef3c7,stroke:#b45309,color:#451a03,stroke-width:1px
    classDef integration fill:#e0e7ff,stroke:#4338ca,color:#1e1b4b,stroke-width:1px
    classDef security fill:#ffe4e6,stroke:#be123c,color:#4c0519,stroke-width:1px
    classDef storage fill:#fff7ed,stroke:#9a3412,color:#431407,stroke-width:1px
    classDef config fill:#ecfeff,stroke:#0e7490,color:#083344,stroke-width:1px
    classDef note fill:#fee2e2,stroke:#991b1b,color:#450a0a,stroke-width:2px,stroke-dasharray: 4 3
```
