# Hayat-e-Nau — WordPress Data Model & Architecture Mapping

**Document Version:** 1.0  
**Status:** Validated against Live WordPress REST API (`atqjamiatulfalah.org/hayat-e-nau`)  

---

## 1. Executive Findings on WordPress Architecture

The source WordPress installation relies on a hybrid architecture combining core WordPress blog posts with Gutenberg page-builder blocks (Spectra / Ultimate Addons for Gutenberg).

Crucially, **the source does not use a dedicated Custom Post Type (CPT) for issues**. Instead, issues and articles are modeled through an intricate category hierarchy, post-meta extensions, and embedded media attachments.

---

## 2. Source Representation Analysis

| Feature / Concept | Original WordPress Implementation | Empirical Evidence / Verification |
| :--- | :--- | :--- |
| **Issues** | Dual mechanism: (1) Category taxonomy under parent Cat ID 2 (`1978`..`2026`), and (2) Annual index posts linking to PDF media attachments. | Category ID 2 contains 45 child year categories. Post ID 35 contains links to 1978 PDF scans. |
| **Articles** | Standard WordPress `post` entities (`post_type: "post"`). | 116 active articles in `/wp-json/wp/v2/posts`. |
| **Editorial Sections** | WordPress category taxonomy under parent Category ID 147 (`sections`). | 18 child categories (ID 148 to 165). |
| **Topics / Tags** | Standard WordPress `tags` (`taxonomy: "post_tag"`). | 85 tags in `/wp-json/wp/v2/tags`. |
| **Authors** | **NOT** standard WordPress user accounts (`/wp/v2/users`). Authors are stored in post-meta `uagb_author_info` (Spectra block metadata) containing `display_name` and `author_link`. | Verified across all 161 posts. 53 distinct names extracted. |
| **PDF Resources** | Stored in `wp-content/uploads/sites/2/[year]/[month]/` as media attachments. | 300 PDF media records identified in `/wp-json/wp/v2/media`. |
| **Issue Covers** | Stored in media library or referenced within post headers. | 170 image assets. |
| **Custom Fields / ACF** | **None found**. ACF or CMB2 plugins are NOT present. All custom data resides in `uagb_*` Gutenberg metadata. | Checked `/wp-json/acf/v3` (returned 404). Post meta inspected directly. |

---

## 3. Entity Mapping Schema: WordPress to Astro

```text
+------------------------------------+        +-----------------------------------+
|       WordPress REST Entity        |        |          Astro Data Model         |
+------------------------------------+        +-----------------------------------+
| Post ID (e.g. 1738)                |  --->  | Article.id ('art-1738')           |
| Post Slug ('shukraan-e-nemat...')  |  --->  | Article.slug (clean kebab-case)   |
| Post Title ('شکرانِ نعمت...')       |  --->  | Article.titleUrdu                 |
| Post Content (clean HTML)          |  --->  | Article.bodyUrdu                  |
| Post Excerpt (or auto 180 chars)   |  --->  | Article.excerptUrdu               |
| Category (Child of ID 147)         |  --->  | Article.sectionId ('fikr-o-nazar')|
| Post Tags / Derived Topics         |  --->  | Article.topicIds (['fiqh', ...])  |
| Post Date ('2026-08-01')           |  --->  | Article.publicationDate           |
| Meta: uagb_author_info.display_name|  --->  | Author (canonicalized id & name)  |
| Category 2 / Year / Post Header    |  --->  | Issue (Jild, Shumara, Musalsal)   |
| Media Attachment (PDF)             |  --->  | Issue.fullPdfResource             |
| Media Attachment (Cover)           |  --->  | Issue.coverImage                  |
+------------------------------------+        +-----------------------------------+
```

---

## 4. Relationship Traversal Validation

1. **Issue $\rightarrow$ Editorial Sections $\rightarrow$ Articles $\rightarrow$ Author & Topic**:
   - An issue (e.g. `jul-sep-2026`) aggregates all articles sharing `issueId: "jul-sep-2026"`.
   - Each article belongs to exactly one `EditorialSection` (e.g. `fikr-o-nazar`), linking back to Category 154.
   - Each article links to a canonical `Author` record (e.g. `rizwan-ul-haq-falahi`).
   - Each article links to one or more `Topic` tags (e.g. `islamic-thought`).

2. **Bidirectional Traversability**:
   - Querying an author returns all their articles (`getArticlesByAuthorSlug`).
   - Querying a section returns all its published articles (`getArticlesBySectionSlug`).
   - Querying a topic returns all tagged articles (`getArticlesByTopicSlug`).
   - Querying an issue returns its table of contents and PDF download (`getArticlesByIssueSlug`).

---

## 5. Architectural Safeguards in Astro

1. **Static Pre-Rendering**: Zero database lookups or API calls at runtime. All static pages are generated into `dist/` at build time.
2. **Deterministic URL Structure**: All URLs follow canonical trailing-slash conventions:
   - `/issues/[slug]/`
   - `/articles/[slug]/`
   - `/authors/[slug]/`
   - `/sections/[slug]/`
   - `/topics/[slug]/`
3. **No Phantom Records**: If an author or issue has 0 articles in the database, counts reflect 0 accurately and gracefully without rendering broken links.