Add JSON-backed data storage layer for bill comments and user accounts

.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Node
+node_modules/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Data files (keep examples)
+data/*.json
+!data/*.json.example
+
+# Logs
+*.log
+*.pid

README.md

@@ -1,141 +1,177 @@
-# 🏛️ Civic Engagement Platform
+# Civic Engagement Platform
 
-## 📘 Project Overview
+## Project Overview
 This project is a civic engagement platform designed to help users interact with political content, track bills, follow political figures, and comment on legislation. It integrates a mix of **MVC** and **N-tier layered architecture** to ensure scalability, maintainability, and clear separation of concerns.
 
 ---
 
-## 🧱 Software Architecture
-<img width="564" height="978" alt="image" src="https://github.com/user-attachments/assets/e3812d80-f48d-490c-81b1-e7c4eb54b228" />
-
-
-### 📊 Architectural Diagram
-<img width="1033" height="499" alt="image" src="https://github.com/user-attachments/assets/66329fdf-17cb-4367-bc82-1bd0256a0907" />
+## Software Architecture
 
+### Architectural Diagram
 
 ---
 
-Presentation Layer (MVC Controllers)
+### Presentation Layer (MVC Controllers)
 
 This is the topmost layer and consists of the controllers and user interface code.
 
-Components:
-
-AppManager
-
-UserController
-
-BillController
-
-PoliticalFigureController
+**Components:**
+- AppManager
+- UserController
+- BillController
+- PoliticalFigureController
 
-Responsibilities:
+**Responsibilities:**
+- Receives user actions (menu selections, input commands)
+- Translates UI requests into service-layer calls
+- Formats data before displaying back to the user
+- Does not implement business logic
 
-Receives user actions (menu selections, input commands)
+**Communication:**
+- Controllers → call → Service Layer Managers
+- Controllers → display output → User
 
-Translates UI requests into service-layer calls
-
-Formats data before displaying back to the user
-
-Does not implement business logic
-
-Communication:
-
-Controllers → call → Service Layer Managers
-Controllers → display output → User
+---
 
-This is equivalent to the Presentation Layer described in the sample file where Spring Controllers handle requests and rely on Services to execute logic 
+### Business / Service Layer
 
-SampleReadMeFile
+This layer contains the core logic of the system.
 
-.
+**Components:**
+- UserManager
+- BillManager
+- PoliticalFigureManager
 
-Business / Service Layer
+**Responsibilities:**
+- Validate inputs received from controllers
+- Apply political app business rules
+- Coordinate interactions between controllers and models
+- Prepare data for display or further processing
 
-This layer contains the core logic of the system. It mirrors the “Service” section of the sample project, which includes InfluencerService, ReviewService, and others 
+**Communication:**
+- Service Layer → reads/writes → Data Layer
+- Service Layer → returns results → Controller Layer
 
-SampleReadMeFile
+---
 
-.
+### Data / Model Layer
 
-Components:
+This layer stores the application's domain data.
 
-UserManager
+**Components:**
+- User
+- Bill
+- Political_Figure
+- JSON Data Storage Handler
 
-BillManager
+**Responsibilities:**
+- Represent core data structures
+- Store attributes of domain entities
+- Support serialization and persistence
+- Provide structured data to service layer
 
-PoliticalFigureManager
+**Communication:**
+- Models → accessed by → Managers
+- Models → return entity data → Managers
 
-Responsibilities:
+---
 
-Validate inputs received from controllers
+## Technology Stack
 
-Apply political app business rules
+| Layer             | Technologies                     |
+|------------------|----------------------------------|
+| Presentation      | React, HTML/CSS, JavaScript      |
+| Service           | Node.js, Express, Python/Flask   |
+| Data Access       | JSON Storage, Supabase, Firebase |
 
-Coordinate interactions between controllers and models
+---
 
-Prepare data for display or further processing
+## JSON Data Storage Layer
 
-Communication:
+The platform includes a JSON-backed data storage layer (`src/data_store.py`) for managing bill comments and user accounts.
 
-Service Layer → reads/writes → Data Layer
-Service Layer → returns results → Controller Layer
+### Features
 
-This is the same pattern as the Business Layer in the sample file, where business logic is kept separate from controllers and models.
+- **Secure Password Hashing**: Uses `passlib[bcrypt]` for industry-standard password hashing
+- **Atomic Writes**: Uses temp file + `os.replace()` for safe concurrent access
+- **File Locking**: Cross-platform file locking (fcntl/msvcrt) with in-process lock fallback
+- **Legacy Support**: Supports migration from plaintext passwords to bcrypt hashes
 
-Data / Model Layer
+### API Reference
 
-This layer stores the application’s domain data, similar to the Model and Repository sections of the sample file 
+#### Comments API
+```python
+from src.data_store import load_comments, save_comments, add_comment, get_comments_for_bill
 
-SampleReadMeFile
+# Load all comments
+comments = load_comments()
 
-.
+# Save all comments
+save_comments({"B001": [{"text": "...", "user": "admin"}]})
 
-Components:
+# Add a comment to a bill
+comment = add_comment("B001", "username", "Comment text")
 
-User
+# Get comments for a specific bill
+bill_comments = get_comments_for_bill("B001")
+```
 
-Bill
+#### Users API
+```python
+from src.data_store import load_users, save_users, create_user, authenticate_user, update_password
 
-Political_Figure
+# Create a new user (password is automatically hashed)
+user = create_user("username", "password", display_name="Display Name")
 
-(Optionally) a file/database storage handler
+# Authenticate a user
+user = authenticate_user("username", "password")
 
-Responsibilities:
+# Update a user's password
+success = update_password("username", "new_password")
+```
 
-Represent core data structures
+### Data Files
 
-Store attributes of domain entities
+Data files are stored in the `data/` directory:
+- `data/comments.json` - Bill comments
+- `data/users.json` - User accounts
 
-Support serialization or persistence (future)
+Example files are provided:
+- `data/comments.json.example`
+- `data/users.json.example`
 
-Provide structured data to service layer
+### Migration Notes
 
-Communication:
+If migrating from the existing `database/users.json` with plaintext passwords:
 
-Models → accessed by → Managers
-Models → return entity data → Managers
+1. The data store automatically supports both legacy plaintext passwords and bcrypt hashes
+2. Users can log in with existing plaintext passwords
+3. Use `update_password()` to upgrade a user's password to bcrypt
+4. New users created via `create_user()` will automatically use bcrypt
 
 ---
 
-## 🧩 Technology Stack
+## Running Tests
 
-| Layer             | Technologies                     |
-|------------------|----------------------------------|
-| Presentation      | React, HTML/CSS, JavaScript      |
-| Service           | Node.js, Express, TypeScript     |
-| Data Access       | Supabase, Firebase               |
+```bash
+# Run data store tests
+python -m unittest tests.test_data_store -v
+```
 
 ---
 
-## 🚀 Setup Instructions
+## Setup Instructions
 
 ```bash
 # Clone the repo
 git clone https://github.com/yourusername/civic-engagement-platform.git
 
-# Install dependencies
+# Install Python dependencies
+pip install -r requirements.txt
+
+# Install Node dependencies
 npm install
 
 # Run the app
 npm start
+```

data/comments.json.example

@@ -0,0 +1,9 @@
+{
+  "B001": [
+    {
+      "text": "This is an example comment on bill B001.",
+      "user": "admin",
+      "timestamp": "2024-01-01T00:00:00Z"
+    }
+  ]
+}

data/users.json.example

@@ -0,0 +1,8 @@
+{
+  "admin": {
+    "password_hash": "$2b$12$examplehashfordemopurposesonly",
+    "display_name": "Administrator",
+    "is_admin": true,
+    "created_at": "2024-01-01T00:00:00Z"
+  }
+}

requirements.txt

@@ -2,3 +2,4 @@ Flask>=2.0
 flask-cors
 Flask==3.1.2
 Flask-Cors==6.0.1
+passlib[bcrypt]>=1.7.4

src/__init__.py

@@ -0,0 +1 @@
+"""Data storage module for the Civic Engagement Platform."""