Update:added documentation folder and added all documentation required

2026-07-30 18:51:18 +02:00
parent cb5acb20a0
commit 6641ea66cb
17 changed files with 742 additions and 419 deletions
--- a/docs/AI_TRANSPARENCY.md
+++ b/docs/AI_TRANSPARENCY.md
@@ -0,0 +1,26 @@
+# AI Usage and Transparency Declaration
+
+## Transparency Statement
+In compliance with COMS3011A lab evaluation guidelines, AI assistance was utilized during the development of this project under pair-programming and pedagogical learning workflows.
+
+## AI Roles & Responsibilities
+
+1. Concept Explanation: Explaining Next.js Server Components, Server Actions, SQLite prepared statements, and CSS Module scoping.
+2. Architecture Design: Structuring local-first database operations, dynamic overdue calculation rules, and component hierarchies.
+3. Troubleshooting & Debugging: Identifying schema mismatch errors (`table tasks has no column named description`) and providing database migration reset steps.
+4. User-Authored Code: All source code modifications were driven interactively and reviewed by the author for complete hands-on learning.
+
+## Conversation Log Transcripts
+
+All raw conversation step logs and prompt histories are preserved locally in the system environment log directory:
+- Path: `C:\Users\mahla\.gemini\antigravity-ide\brain\1c0b1ab9-bf0e-425f-a67e-38d23d353de7\.system_generated\logs\transcript.jsonl`
+- Full Transcript: `C:\Users\mahla\.gemini\antigravity-ide\brain\1c0b1ab9-bf0e-425f-a67e-38d23d353de7\.system_generated\logs\transcript_full.jsonl`
+
+## Summary of AI Interactions
+- Query 1: Diagnosed `SqliteError: table tasks has no column named description` and provided schema update steps.
+- Query 2: Explained Turbopack workspace root detection warnings.
+- Query 3: Explained Next.js Server Actions, SQL injection prevention via prepared statements (`?`), and server cache revalidation (`revalidatePath`).
+- Query 4: Detailed line-by-line breakdown of TSX components, React hooks (`useState`, `useRef`), and prop passing.
+- Query 5: Refactored page inline styles into scoped CSS Modules (`page.module.css`).
+- Query 6: Harmonized UI design system with light page background, royal blue typography, and dark component cards.
+- Query 7: Built Archived Tasks popup dialog with unarchiving / restoring capabilities.
--- a/docs/DATABASE_DESIGN.md
+++ b/docs/DATABASE_DESIGN.md
@@ -0,0 +1,37 @@
+# Database Design Documentation
+
+## Overview
+This project uses SQLite as a local-first, single-user relational database engine via the `better-sqlite3` driver for Node.js.
+
+## Table Schema: `tasks`
+
+```sql
+CREATE TABLE IF NOT EXISTS tasks (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    title TEXT NOT NULL,
+    description TEXT,
+    due_date TEXT NOT NULL,
+    topic TEXT NOT NULL,
+    status TEXT CHECK(status IN ('Todo','In-Progress','Complete')) NOT NULL DEFAULT 'Todo',
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    is_archived BOOLEAN NOT NULL DEFAULT 0
+);
+```
+
+## Field Specifications
+
+| Column Name | Data Type | Constraints | Description |
+| :--- | :--- | :--- | :--- |
+| `id` | `INTEGER` | `PRIMARY KEY AUTOINCREMENT` | Unique identifier for each task record. |
+| `title` | `TEXT` | `NOT NULL` | Short summary title of the task. |
+| `description` | `TEXT` | Optional | Extended notes or detailed instructions for the task. |
+| `due_date` | `TEXT` | `NOT NULL` | Due date formatted as ISO string (`YYYY-MM-DD`). |
+| `topic` | `TEXT` | `NOT NULL` | Categorical topic tag (e.g. `SDP`, `Personal`). |
+| `status` | `TEXT` | `CHECK(status IN ('Todo','In-Progress','Complete'))` | Current lifecycle state of the task. Default is `'Todo'`. |
+| `created_at` | `TIMESTAMP` | `DEFAULT CURRENT_TIMESTAMP` | System timestamp recorded on task creation. |
+| `is_archived` | `BOOLEAN` | `DEFAULT 0` | Soft-deletion flag. `0` indicates active, `1` indicates archived. |
+
+## Schema Design Decisions
+
+1. Soft-Deletion (Archiving): Tasks are never permanently deleted from the database. Setting `is_archived = 1` retains all historical data while hiding archived tasks from active views.
+2. Dynamic Overdue State: The database schema explicitly excludes an `is_overdue` column. Storing `is_overdue` in a database column creates stale data when dates pass. Overdue status is dynamically computed at read-time by comparing `due_date` against the current date for non-completed tasks.
--- a/docs/RELATIONSHIPS.md
+++ b/docs/RELATIONSHIPS.md
@@ -0,0 +1,56 @@
+# Entity Relationships and Data Lifecycle
+
+## System Architecture Model
+
+The application operates as a single-table relational model optimized for local-first desktop usage.
+
+```mermaid
+classDiagram
+    class Task {
+        +int id
+        +string title
+        +string description
+        +string due_date
+        +string topic
+        +TaskStatus status
+        +boolean is_archived
+        +string created_at
+        +boolean computeIsOverdue()
+    }
+
+    class TaskStatus {
+        <<enumeration>>
+        Todo
+        In-Progress
+        Complete
+    }
+
+    Task "1" -- "1" TaskStatus : holds
+```
+
+## State Transitions & Task Lifecycle
+
+A task record moves through defined state transitions:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Todo : Task Created
+    Todo --> InProgress : User updates status
+    InProgress --> Complete : Task completed
+    Complete --> InProgress : Reopened
+    
+    Todo --> Archived : Soft Deleted
+    InProgress --> Archived : Soft Deleted
+    Complete --> Archived : Soft Deleted
+
+    Archived --> Todo : Restored (Unarchived)
+```
+
+## Overdue Derivation Logic
+
+Overdue state is derived dynamically at query runtime using the following logic:
+
+- Condition 1: `status !== 'Complete'`
+- Condition 2: `due_date < current_date` (ISO format `YYYY-MM-DD`)
+
+If both conditions are met, `is_overdue` evaluates to `true`. Completed or archived tasks are never marked as overdue.