News Els — Technical Architecture & Implementation Plan

📑 Document Contents

1. Architectural Overview & Design System

2. Database Schema (els.news.db.json)

3. Technology Stack Selection

4. Core Client Workspaces & Features

5. Embedded Hot Polls & Discussion Engine

6. Research Vault & DocStore Image Integration

7. Implementation Plan & Milestones

1. Architectural Overview & Design System

News Els (`https://news.elsastry.com`) operates as a standalone module within the ELS suite, sharing account credentials, authentication sessions (`/api/auth/*`), and visual styling tokens with all existing ELS applications.

🔑 Unified SSO Credentials

Seamlessly authenticated via ELS Bearer session tokens (`localStorage.els_token`). Users register or sign in once and access News Els without secondary logins.

🎨 Identical Visual Theme Engine

Implements dark/light mode toggle with CSS tokens (`--bg-dark`, `--bg-card`, `--accent-gold`, `--accent-blue`, `--accent-cyan`, `--accent-green`, `--font-main: Inter`).

2. Database Schema (`els.news.db.json`)

All news articles, user category preferences, research vault clippings, hot polls, votes, and discussion comments are persisted in a separate database file stored at /var/lib/els/data/els.news.db.json.

Collection Key	Purpose	Key Data Fields
`news_preferences`	Stores user feed settings & alert rules	`user_id`, `categories` (tech, finance, education, world), `detail_level` (snippet, brief, in-depth), `keyword_alerts`, `push_enabled`
`news_articles`	Crawled news snippets & metadata	`id`, `title`, `url`, `publisher`, `category`, `snippet_2lines`, `key_bullets`, `image_url`, `published_at`
`user_research_vault`	Saved research items for presentations/study	`id`, `user_id`, `article_id`, `research_folder` (e.g. "Education Policy"), `user_notes`, `highlight_clips`, `doc_image_url` (doc.elsastry link), `share_code`
`hot_polls`	Community polls tied to news topics	`id`, `user_id`, `article_id`, `title`, `category`, `options` ([{id, text, votes}]), `total_votes`, `status`
`poll_votes`	Per-user vote tracking (1 vote per user)	`id`, `poll_id`, `user_id`, `option_id`, `voted_at`
`poll_comments`	Discussion thread on hot topic polls	`id`, `poll_id`, `user_id`, `display_name`, `comment_text`, `created_at`

3. Technology Stack Selection

Client Side (Simple & Professional Vanilla Stack)

HTML5 & CSS3: Custom responsive layout with dark/light themes, card grids, modal overlays, and progress badges. Zero heavy npm framework bloat.
JavaScript (ES Modules): Modular client architecture (`js/news-app.js`, `js/news-api.js`, `js/news-polls.js`, `js/news-vault.js`).

Server Side (Dual Node.js + Python AI Engine)

Node.js Express API Router (`news-routes.js`): Handles authentication checks, database CRUD operations on `els.news.db.json`, WebSocket live poll broadcast, and DocStore image bridge.
Python FastAPI AI Summarizer (`main.py`): Runs polite RSS/HTML crawlers (`feedparser`, `httpx`, `beautifulsoup4`) and generates 2-sentence AI summaries and bullet points using Python NLP / free LLM APIs.

4. Core Client Workspaces & Features

📰 1. Global News Digest Feed

Category filter bar (Tech, Finance, Education, World, Science). Toggle detailing levels (Short 2-Sentence Snippet / Executive Brief / In-Depth Synthesis). 1-Click 📌 Save to Research Vault and 📊 Create Hot Poll buttons on every snippet card.

📌 2. Saved Research Vault

Organize saved clips into custom research folders (e.g. "Education Policy Across Countries"). Add custom notes, highlight excerpts, attach images (hosted on doc.elsastry.com), and generate timestamped share links.

🔥 3. Hot Polls Community Hub

Dedicated section for trending news polls. Users publish polls on hot news events, cast votes with real-time percentage progress bars, and join discussion threads.

⚙️ 4. Preferences & Alerts Engine

Configure favorite categories, alert keywords, detailing levels, and push notification triggers for major breaking events.

5. Embedded Hot Polls & Discussion Engine

When a news story generates debate (e.g., new education policies, tech regulations, economic shifts), users can instantly attach a Hot Poll to the snippet or publish a standalone poll.

6. Research Vault & DocStore Image Integration

When users save research clippings with custom images or diagrams, images are uploaded directly to doc.elsastry.com (DocStore API). The returned secure URL is stored in els.news.db.json under the user's research item.

// DocStore Image Link Flow
const uploadImageToDocStore = async (fileBlob) => {
  const formData = new FormData();
  formData.append("file", fileBlob);

  const res = await fetch("https://doc.elsastry.com/api/doc-store/upload", {
    method: "POST",
    headers: { Authorization: `Bearer ${getToken()}` },
    body: formData
  });

  const data = await res.json();
  return data.fileUrl; // e.g. "https://doc.elsastry.com/api/doc-store/files/img_987213.png"
};

7. Implementation Plan & Milestones

🚀 Implementation Roadmap

Phase 1 (Domain & Service Config): Add NEWS_DOMAIN="news.elsastry.com" to deploy.env, update scripts/render.sh, and configure Caddy block in generated/Caddyfile.
Phase 2 (Database Engine): Create app/news-server/news-db.js managing els.news.db.json (Preferences, Articles, Vault, Hot Polls, Comments).
Phase 3 (Server REST & AI APIs): Implement Node.js Express routes (app/news-server/news-routes.js) and Python FastAPI summarizer (app/news-server/main.py).
Phase 4 (Client Frontend Build): Build clean, responsive single-page web app in app/news-client/index.html, css/news.css, and JS modules (`js/news-app.js`, `js/news-polls.js`, `js/news-vault.js`).
Phase 5 (Verification & Deployment): Deploy to news.elsastry.com with automatic Let's Encrypt SSL certificate.