Knowledge Commons

Requirements and Specifications: Difference between revisions

VisualWikitext
Created page with "This page."
 
No edit summary
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
This page.
== Wiki Farm PARA Mode ==
=== Functional Requirements and Technical Specification ===
 
'''Document purpose:''' This specification defines the first implementation of the structured personal knowledge management ("PARA Wiki") mode for a MediaWiki-based wiki farm. It is intended to be sufficiently explicit for use by a software developer or coding AI.
 
'''Status:''' Draft implementation specification 
'''Version:''' 1.0 
'''Target platform:''' MediaWiki with Cargo and custom extension code 
'''Primary design principle:''' Preserve normal MediaWiki behavior wherever practical, while adding an optional structured PKM mode.
 
---
 
== 1. Product Scope ==
 
=== 1.1 Wiki Modes ===
 
When a user creates a new wiki, the system shall support a configurable '''Wiki Mode'''.
 
Initial supported modes:
 
{| class="wikitable"
! Mode !! Description
|-
| `standard` || Flexible MediaWiki experience with optional starter content. Structured PARA rules are not enforced.
|-
| `para` || Structured personal knowledge management mode inspired by PARA and extended with Page Type, Page Status, Areas, Projects, Topics, type-specific metadata, and topic-specific metadata.
|}
 
The architecture shall allow additional modes to be introduced later without redesigning the page metadata model.
 
The selected Wiki Mode shall be stored at the wiki level, not page level.
 
The user-facing name shall be '''PARA Wiki''', but documentation should describe it as "inspired by the PARA method" rather than implying that every feature is part of Tiago Forte's original PARA methodology.
 
---
 
== 2. Core Concepts ==
 
Every normal content page in PARA Wiki mode shall have:
 
* exactly one <code>PageType</code>
* exactly one <code>PageStatus</code>
 
A page may also have:
 
* zero or one <code>ParentArea</code> when <code>PageType=Area</code>
* zero or more <code>RelatedAreas</code> when <code>PageType!=Area</code>
* zero or more <code>RelatedProjects</code>
* zero or more <code>RelatedTopics</code>
* zero or more type-specific metadata fields
* zero or more topic-specific metadata fields
 
Conceptual definitions:
 
{| class="wikitable"
! Dimension !! User-facing question !! Meaning
|-
| Type || How will I use this page? || The functional role of the page.
|-
| Status || Is it currently relevant/active? || The lifecycle state of the page.
|-
| Area || What ongoing part of my life does it support? || An ongoing responsibility, activity, or intentionally maintained domain.
|-
| Project || What outcome does it support? || A finite outcome or goal.
|-
| Topic || What is it about? || A subject used to connect related pages.
|}
 
---
 
== 3. Page Types ==
 
The application shall initially support exactly six Page Types. Users shall not be able to create custom Page Types in version 1.
 
{| class="wikitable"
! PageType !! Description !! Guidance
|-
| `Study` || Notes derived from a source or structured learning. || Knowledge being acquired from a particular source, class, book, course, lecture, etc.
|-
| `Journal` || Chronological experience or reflection. || What happened or what the user experienced.
|-
| `Idea` || A concept, conclusion, insight, or synthesized thought. || An understanding the user developed rather than merely collected.
|-
| `Project` || Information supporting an intended finite outcome. || Something the user is trying to complete.
|-
| `Area` || An ongoing part of life that the user maintains or develops. || An ongoing responsibility, activity, or domain without a defined end.
|-
| `Resource` || Information collected primarily for future reference. || Information likely to have more use in the future than at the time it is stored.
|}
 
Recommended stable internal identifiers:
 
<pre>
study
journal
idea
project
area
resource
</pre>
 
---
 
== 4. Page Statuses ==
 
The application shall initially support three Page Status values:
 
<pre>
inception
active
archived
</pre>
 
Users shall not be able to create custom statuses in version 1.
 
{| class="wikitable"
! PageType !! Inception !! Active !! Archived
|-
| Study || No || Yes || Yes
|-
| Journal || No || Yes || Yes
|-
| Idea || No || Yes || Yes
|-
| Project || Yes || Yes || Yes
|-
| Area || Yes || Yes || Yes
|-
| Resource || No || Yes || Yes
|}
 
Definitions:
 
{| class="wikitable"
! Status !! Meaning
|-
| `Inception` || Being considered or developed but not yet committed.
|-
| `Active` || Currently relevant, maintained, pursued, or available for normal use.
|-
| `Archived` || Retained but no longer active.
|}
 
Status shall affect default inclusion in views, selectors, reports, workflows, and search filters.
 
Status shall '''not''' determine authorization, sharing, privacy, or security permissions.
 
Archived pages shall remain directly accessible to users who otherwise have permission to view them.
 
---
 
== 5. Area Model ==
 
=== 5.1 Area Definition ===
 
An Area is an ongoing responsibility, activity, or something the user intentionally maintains or develops over time.
 
Examples include Personal, Family, Household, Learning, Career, Travel & Vacations, Hobbies, Photography, Cooking, and Fitness & Nutrition.
 
=== 5.2 Parent Area ===
 
An Area page may have zero or one <code>ParentArea</code>.
 
A page whose <code>PageType=Area</code> shall not use <code>RelatedAreas</code>.
 
Examples:
 
<pre>
Hobbies
  ParentArea = NULL
 
Photography
  ParentArea = Hobbies
 
Cooking
  ParentArea = Hobbies
 
Career
  ParentArea = NULL
 
Skills development
  ParentArea = Career
</pre>
 
A top-level Area is defined as:
 
<pre>
PageType = Area
ParentArea = NULL
</pre>
 
The system shall prevent an Area from being its own parent and shall prevent circular Area relationships.
 
The Area hierarchy shall support an arbitrary practical depth unless implementation limitations require a documented maximum.
 
=== 5.3 Related Areas ===
 
A non-Area page may have zero or more <code>RelatedAreas</code>.
 
Each value shall reference an existing page whose <code>PageType=Area</code>.
 
When assigning an Area through the UI, the default picker shall show active Area pages. The user may enable an option such as '''Include archived Areas'''.
 
The Area picker should display hierarchy where practical.
 
The system should recommend no more than three Related Areas per page but shall not enforce a hard maximum.
 
---
 
== 6. Project Model ==
 
A Project is a page whose <code>PageType=Project</code>.
 
A Project shall normally have at least one <code>RelatedArea</code>, although this shall be a quality warning rather than a hard validation rule.
 
A page may have zero or more <code>RelatedProjects</code>.
 
Each Related Project shall reference an existing page whose <code>PageType=Project</code> and is Active by default in selectors. The picker shall allow archived Projects to be included optionally.
 
The system shall prevent a Project page from assigning itself as a Related Project.
 
Project hierarchy / <code>ParentProject</code> is explicitly out of scope for version 1, but the schema shall not preclude adding it later.
 
---
 
== 7. Project-to-Area Defaulting ==
 
When a Project is assigned to a page:
 
# Read the selected Project's <code>RelatedAreas</code>.
# Add any missing Project Areas to the edited page's <code>RelatedAreas</code>.
# Do not remove any existing Areas.
# Allow the user to remove any newly added Areas before saving.
# Once the page is saved, the values are independent.
 
This behavior is '''default copying''', not dynamic inheritance.
 
If the Project's Areas change later, existing pages assigned to that Project shall not automatically change.
 
---
 
== 8. Topic Model ==
 
=== 8.1 Topic Is Not a Page Type ===
 
<code>Topic</code> shall not be added as a seventh PageType. PageType answers '''How will I use this page?''' Topic answers '''What is this page about?'''
 
=== 8.2 Topics as First-Class Classification Objects ===
 
Topics shall be first-class application objects.
 
Recommended implementation:
 
<pre>
Topic:<TopicName>
</pre>
 
using a dedicated MediaWiki namespace.
 
Examples:
 
<pre>
Topic:Python
Topic:Programming
Topic:Freshman Courses
Topic:Rome
</pre>
 
Topic namespace pages are classification/hub objects and are not ordinary PARA knowledge pages. Topic pages shall not require a PageType.
 
A Topic should support at least:
 
{| class="wikitable"
! Field !! Requirement
|-
| TopicName || Required, unique within the wiki
|-
| TopicStatus || Active or Archived
|-
| Description || Optional
|-
| RelatedTopics || Optional/future-safe
|-
| MetadataDefinition || Optional structured definition of topic-specific fields
|-
| CreatedAt || System managed
|-
| UpdatedAt || System managed
|}
 
Version 1 may omit RelatedTopics and MetadataDefinition UI if necessary, but the data model should allow future implementation.
 
=== 8.3 Related Topics ===
 
Normal content pages may have zero or more <code>RelatedTopics</code>.
 
Each Related Topic shall reference an existing Topic object. Default picker behavior shall show active Topics, with an option to include archived Topics.
 
The system should recommend no more than three Topics per page for simplicity but shall not enforce a hard maximum.
 
=== 8.4 Topic Creation ===
 
The RelatedTopics control should allow selecting an existing Topic and optionally creating a new Topic inline, subject to permissions.
 
The system shall prevent accidental duplicate Topics caused only by case differences or excess whitespace, consistent with MediaWiki title behavior.
 
---
 
== 9. Topic-Specific Metadata ==
 
The architecture shall support topic-specific metadata.
 
For example, <code>Topic:Book</code> could define Author, ISBN, Publisher, and PublicationDate. <code>Topic:Vehicle</code> could define Make, Model, ModelYear, and VIN.
 
Topic metadata and entity/schema metadata may eventually become separate concepts. Version 1 should therefore implement topic-specific metadata modularly rather than permanently coupling metadata schemas to Topic processing.
 
Recommended abstraction:
 
<pre>
MetadataDefinition
MetadataField
MetadataAssignment
MetadataValue
</pre>
 
---
 
== 10. Type-Specific Metadata ==
 
Each Page Type may expose additional metadata. The following fields are illustrative rather than mandatory for version 1.
 
{| class="wikitable"
! PageType !! Possible metadata
|-
| Study || SourceType, SourceTitle, Author, Instructor, Institution, StartDate, EndDate, Progress, URL, ISBN
|-
| Journal || JournalDate, StartDate, EndDate, Location
|-
| Idea || IdeaDate, Confidence, SourcePages
|-
| Project || StartDate, TargetDate, CompletionDate, Outcome, Progress
|-
| Area || ReviewFrequency, LastReviewed
|-
| Resource || SourceURL, SourceDate, Author
|}
 
Potential future Project Outcome values include <code>completed</code>, <code>abandoned</code>, and <code>cancelled</code>. Outcome shall remain separate from PageStatus.
 
The type-specific metadata subsystem shall be extensible without schema redesign.
 
---
 
== 11. Unclassified Page Rule ==
 
Every non-Area page should normally have at least one of <code>RelatedAreas</code>, <code>RelatedProjects</code>, or <code>RelatedTopics</code>.
 
This shall not be a hard save-time validation rule.
 
If all three are empty, the page shall be classified as '''Unclassified''' for quality/reporting purposes.
 
The page shall display a non-blocking notification such as:
 
<pre>
This page is not currently associated with an Area, Project, or Topic.
</pre>
 
The user's Status / Wiki Health page shall include an Unclassified Pages section and count.
 
Area pages are exempt from this rule.
 
---
 
== 12. Wiki Health / Status Page ==
 
PARA Wiki mode shall include a system-generated or extension-generated '''Status''' or '''Wiki Health''' page.
 
Minimum metrics:
 
{| class="wikitable"
! Metric !! Definition
|-
| Unclassified Pages || Non-Area pages with no Area, Project, or Topic
|-
| Active Projects Without Areas || Project pages with no RelatedAreas
|-
| Top-Level Areas || Active Area pages with ParentArea=NULL
|-
| Sub-Areas || Active Area pages with ParentArea set
|-
| Archived Pages || Count grouped by PageType
|-
| Areas With No Associated Content || Areas with no child Areas and no related pages
|-
| Active Projects With No Recent Activity || Optional if reliable activity logic is available
|}
 
All metrics should link to filtered page lists.
 
---
 
== 13. Page Metadata UI ==
 
Recommended user-facing labels:
 
<pre>
Type
Status
Parent Area
Related Areas
Related Projects
Topics
</pre>
 
Recommended internal field names:
 
<pre>
PageType
PageStatus
ParentArea
RelatedAreas
RelatedProjects
RelatedTopics
</pre>
 
Do not use numbered fields such as <code>Area1</code>, <code>Area2</code>, <code>Area3</code>, <code>Project1</code>, etc.
 
For an Area page, show Type, Status, Parent Area, Related Projects if applicable, and Topics. Hide/disable Related Areas.
 
For a non-Area page, show Type, Status, Related Areas, Related Projects, and Topics. Hide Parent Area.
 
When PageType changes, the UI shall dynamically re-evaluate valid statuses and applicable fields.
 
---
 
== 14. Cargo Storage Model ==
 
Cargo shall be used for structured querying unless implementation testing identifies a technical blocker.
 
Recommended main table: <code>WikiPages</code>.
 
Illustrative schema:
 
<pre>
{{#cargo_declare:
_table=WikiPages
|PageType=String
|PageStatus=String
|ParentArea=Page
|RelatedAreas=List (,) of Page
|RelatedProjects=List (,) of Page
|RelatedTopics=List (,) of Page
}}
</pre>
 
Requirements:
 
* Store page names as Cargo <code>Page</code> values rather than integer IDs unless testing identifies a strong reason otherwise.
* Use Cargo List fields for RelatedAreas, RelatedProjects, and RelatedTopics.
* Use Cargo-supported list querying such as <code>HOLDS</code> rather than manually parsing comma-separated strings.
* Topic references using a dedicated namespace may be stored as full titles such as <code>Topic:Python</code>.
* Topic data should use a separate Cargo table such as <code>Topics</code>.
* Type-specific metadata may use separate Cargo tables rather than making the main table excessively wide.
 
---
 
== 15. Data Integrity Rules ==
 
{| class="wikitable"
! Rule !! Enforcement
|-
| PageType required || Hard
|-
| PageStatus required || Hard
|-
| PageStatus valid for PageType || Hard
|-
| Area has at most one ParentArea || Hard
|-
| Area cannot use RelatedAreas || Hard
|-
| Non-Area cannot use ParentArea || Hard
|-
| ParentArea references Area page || Hard
|-
| RelatedAreas reference Area pages || Hard
|-
| RelatedProjects reference Project pages || Hard
|-
| RelatedTopics reference Topic objects || Hard
|-
| Area cannot parent itself || Hard
|-
| Area hierarchy cannot contain cycles || Hard
|-
| Project cannot relate to itself || Hard
|-
| Non-Area should have Area, Project, or Topic || Warning
|-
| Project should have at least one Area || Warning
|-
| More than three Areas or Topics || Advisory only
|}
 
Invalid metadata submitted through APIs or non-UI mechanisms shall be rejected consistently with UI validation.
 
---
 
== 16. Archived Object Behavior ==
 
Archived pages remain accessible.
 
Default behavior:
 
* exclude archived Areas from Area pickers
* exclude archived Projects from Project pickers
* exclude archived Topics from Topic pickers
* optionally exclude archived pages from default dashboards and views
* allow users to explicitly include archived content
* direct links to archived pages continue to work
 
Archived shall not mean deleted and shall not modify sharing/privacy permissions.
 
---
 
== 17. Search and Browse Behavior ==
 
PARA Wiki shall support filtering/browsing by PageType, PageStatus, Area, Project, and Topic.
 
Examples:
 
<pre>
Active Study pages in Learning
Resources related to Plan Italy vacation
Pages about Python
Archived pages in Photography
Unclassified pages
</pre>
 
Area browse pages should be able to derive and display child Areas, directly related pages, active Projects associated with the Area, and optionally descendant-Area content.
 
Project browse pages should display Project metadata, Related Areas, pages assigned to the Project, and status/outcome information when implemented.
 
Topic pages should display the Topic description, pages assigned to the Topic, counts by PageType, and derived related Areas and Projects.
 
---
 
== 18. Onboarding ==
 
When creating a PARA Wiki, onboarding should explain:
 
<pre>
Type: How will I use this page?
Status: Is it currently relevant/active?
Area: What ongoing part of my life does it support?
Project: What outcome does it support?
Topic: What is it about?
</pre>
 
The user may optionally import starter pages. Starter pages shall be selectable; users should not be forced to import the entire sample set.
 
All imported starter pages should default to <code>PageStatus=Active</code> unless explicitly defined otherwise.
 
---
 
== 19. Starter Page Dataset ==
 
{| class="wikitable"
! PageName !! PageType !! ParentArea !! RelatedAreas !! RelatedProjects !! RelatedTopics
|-
| Personal || Area ||  ||  ||  ||
|-
| Long-term goals || Resource ||  || Personal ||  ||
|-
| Weekly tasks || Resource ||  || Personal ||  ||
|-
| Gift ideas || Resource ||  || Personal ||  ||
|-
| Daily Journal || Journal ||  || Personal ||  ||
|-
| Fitness & Nutrition || Area ||  ||  ||  ||
|-
| Tips for healthy eating || Resource ||  || Fitness & Nutrition ||  ||
|-
| Yoga || Area || Fitness & Nutrition ||  ||  ||
|-
| Why yoga helps me || Idea ||  || Fitness & Nutrition ||  ||
|-
| Household || Area ||  ||  ||  ||
|-
| Products || Resource ||  || Household ||  ||
|-
| Household Technology || Resource ||  || Household ||  ||
|-
| Subscriptions || Resource ||  || Household ||  ||
|-
| Family || Area ||  ||  ||  ||
|-
| Family traditions || Resource ||  || Family ||  ||
|-
| Family tree || Resource ||  || Family ||  ||
|-
| Friends & Social Activities || Area ||  ||  ||  ||
|-
| Poker night planning || Resource ||  || Friends & Social Activities ||  ||
|-
| Why Small Gatherings Are More Enjoyable || Idea ||  || Friends & Social Activities ||  ||
|-
| Volunteering || Area ||  ||  ||  ||
|-
| Past volunteering || Resource ||  || Volunteering ||  ||
|-
| Volunteering opportunities || Resource ||  || Volunteering ||  ||
|-
| Vehicles || Area ||  ||  ||  ||
|-
| Honda Accord 2025 || Resource ||  || Vehicles ||  ||
|-
| Vehicles being considered for purchase || Resource ||  || Vehicles ||  ||
|-
| Learning || Area ||  ||  ||  ||
|-
| List of schools & courses attended || Resource ||  || Learning ||  ||
|-
| List of books I have read || Resource ||  || Learning ||  ||
|-
| Intro to Python || Study ||  || Learning, Career || Complete course on Python || Programming, Python
|-
| Psychology 103 || Study ||  || Learning || University Degree || Freshman Courses
|-
| Music Theory 202 || Study ||  || Learning || University Degree || Freshman Courses
|-
| Travel & Vacations || Area ||  ||  ||  ||
|-
| Bucket list || Resource ||  || Travel & Vacations ||  ||
|-
| Past vacations || Resource ||  || Travel & Vacations ||  ||
|-
| Spain Vacation Journal || Journal ||  || Travel & Vacations ||  ||
|-
| Travel loyalty programs || Resource ||  || Travel & Vacations ||  ||
|-
| Entertainment || Area ||  ||  ||  ||
|-
| Concerts I might want to see || Resource ||  || Entertainment ||  ||
|-
| Concert Journal || Journal ||  || Entertainment ||  ||
|-
| Movies to rewatch || Resource ||  || Entertainment ||  ||
|-
| Hobbies || Area ||  ||  ||  ||
|-
| Photography || Area || Hobbies ||  ||  ||
|-
| Canon EOS R10 || Resource ||  || Photography ||  ||
|-
| Understanding Exposure by Bryan Peterson || Study ||  || Photography ||  ||
|-
| Tips for Low Light Photography || Resource ||  || Photography ||  ||
|-
| Cooking || Area || Hobbies ||  ||  ||
|-
| Career || Area ||  ||  ||  ||
|-
| Skills development || Area || Career ||  ||  ||
|-
| Potential employers || Resource ||  || Career ||  ||
|-
| Create family vacation photo book || Project ||  || Family, Photography ||  ||
|-
| Replace kitchen floor || Project ||  || Household ||  ||
|-
| Plan Italy vacation || Project ||  || Travel & Vacations, Family ||  ||
|-
| Hotels in Rome || Resource ||  || Travel & Vacations, Family || Plan Italy vacation ||
|-
| Complete course on Python || Project ||  || Career, Learning ||  ||
|-
| University Degree || Project ||  || Learning ||  ||
|}
 
Required starter Topics if the corresponding starter pages are imported:
 
<pre>
Programming
Python
Freshman Courses
</pre>
 
Starter Project and Topic dependencies shall be handled automatically. No imported starter page may contain a dangling reference.
 
---
 
== 20. Page Creation Workflow ==
 
# User enters page title.
# User selects PageType.
# System presents valid PageStatus values.
# Default status should normally be Active.
# If PageType=Area, show ParentArea and hide RelatedAreas.
# Otherwise show RelatedAreas and hide ParentArea.
# Show RelatedProjects.
# Show RelatedTopics.
# Load type-specific metadata fields.
# Load topic-specific metadata fields as Topics are selected.
# Validate hard rules.
# Display advisory warnings separately.
# Save page and structured metadata atomically where practical.
 
The system should minimize clicks and avoid repeated confirmation screens.
 
---
 
== 21. Editing Workflow ==
 
Existing metadata shall load into the editor.
 
Changing PageType shall re-evaluate valid statuses, update visible fields, warn before discarding invalid metadata, and never silently destroy user metadata.
 
Example: changing Area to Resource may safely offer to convert ParentArea to RelatedAreas. Changing Resource to Area with multiple RelatedAreas shall require the user to choose zero or one ParentArea.
 
---
 
== 22. Page Rename / Move Behavior ==
 
Because Page-valued metadata references page titles, page moves must preserve referential integrity.
 
The extension shall test MediaWiki/Cargo behavior for page moves. If Cargo does not automatically update references reliably, custom extension logic shall update ParentArea, RelatedAreas, RelatedProjects, and RelatedTopics as appropriate.
 
Topic page moves shall similarly update RelatedTopics references.
 
A maintenance script shall detect dangling references.
 
---
 
== 23. Page Delete Behavior ==
 
Deleting a referenced Area, Project, or Topic requires explicit handling.
 
Preferred behavior:
 
# Display dependency count before deletion.
# Provide links to referencing pages.
# Do not silently remove relationship values.
# Allow administrative forced deletion if MediaWiki permissions permit.
# After deletion, Wiki Health shall identify dangling references until repaired.
 
Future enhancement: reassignment during deletion.
 
---
 
== 24. Permissions and Privacy ==
 
PARA classification is independent of access control.
 
Do not use PageStatus, PageType, Area, Project, or Topic as security boundaries.
 
All extension-generated lists and Cargo queries must respect MediaWiki read permissions and must not leak page titles or metadata for pages the viewer cannot access.
 
This applies to Area pages, Project pages, Topic pages, dashboards, autocomplete, selectors, API endpoints, counts, and search results.
 
---
 
== 25. API Requirements ==
 
The extension should expose structured operations through MediaWiki's API or a clearly defined REST interface.
 
Minimum operations:
 
<pre>
Get page classification metadata
Set page classification metadata
List valid PageTypes
List valid statuses for a PageType
Search/select Areas
Search/select Projects
Search/select Topics
Create Topic
Get Wiki Health counts
List Unclassified pages
</pre>
 
API validation rules shall match UI validation rules.
 
Example payload:
 
<pre>
{
  "pageType": "study",
  "pageStatus": "active",
  "relatedAreas": ["Learning", "Career"],
  "relatedProjects": ["Complete course on Python"],
  "relatedTopics": ["Topic:Programming", "Topic:Python"]
}
</pre>
 
---
 
== 26. Extension Architecture ==
 
Recommended implementation: one custom MediaWiki extension responsible for structured PKM behavior.
 
Working placeholder name: <code>WikiFarmPKM</code>.
 
Responsibilities:
 
* Wiki Mode configuration
* metadata validation
* metadata UI integration
* PageType/PageStatus rules
* Area hierarchy logic
* Project default-Area behavior
* Topic namespace behavior
* Cargo integration
* Wiki Health dashboard
* API endpoints
* maintenance scripts
* onboarding support hooks
* page move/delete consistency logic
 
Avoid scattering core business rules across templates, JavaScript snippets, and wiki pages. Templates may render data, but the extension should be the validation source of truth.
 
---
 
== 27. Configuration ==
 
Recommended wiki-level configuration:
 
<pre>
$wgWikiFarmMode = 'para';
</pre>
 
or an equivalent per-wiki application configuration.
 
Recommended configurable constants:
 
<pre>
AllowedPageTypes
AllowedStatuses
StatusesByPageType
DefaultPageStatus
TopicNamespaceId
RecommendMaxAreas
RecommendMaxTopics
EnableProjectAreaDefaults
EnableWikiHealth
</pre>
 
Do not hard-code numeric namespace IDs without a configuration constant.
 
---
 
== 28. Namespace Recommendation ==
 
Use a dedicated namespace:
 
<pre>
Topic:
</pre>
 
Do not place Topic hub pages in the main namespace.
 
Topic namespace pages should remain normal MediaWiki pages where practical so they retain revisions, watchability, linking, discussion, search, and history.
 
---
 
== 29. Query Examples ==
 
Conceptual Cargo queries:
 
<pre>
RelatedAreas HOLDS 'Photography'
</pre>
 
<pre>
PageType='Project'
AND PageStatus='Active'
AND RelatedAreas HOLDS 'Family'
</pre>
 
<pre>
RelatedTopics HOLDS 'Topic:Python'
</pre>
 
Unclassified conceptually means PageType is not Area and RelatedAreas, RelatedProjects, and RelatedTopics are all empty.
 
Implementation shall use exact Cargo syntax appropriate to the installed Cargo version.
 
---
 
== 30. Performance Requirements ==
 
Design for at least:
 
<pre>
100,000 normal pages
10,000 Topics
10,000 Areas/Projects combined
</pre>
 
without schema redesign.
 
Selectors/autocomplete must not load all matching objects into the browser. Use server-side search/autocomplete for large lists.
 
Wiki Health calculations should avoid expensive full scans on every page view. Acceptable approaches include cached counts, scheduled refresh, incremental updates on edit hooks, or indexed Cargo queries. The chosen approach shall be documented.
 
---
 
== 31. Accessibility and UX ==
 
All classification controls shall be keyboard accessible. Do not rely on color alone for status.
 
Multi-select fields should support typeahead search, keyboard selection, removal of values, and visible Area hierarchy where practical.
 
Warnings shall be clearly distinguishable from hard errors.
 
---
 
== 32. Logging and Auditability ==
 
Metadata changes should be visible in page revision history where practical.
 
At minimum, administrators should be able to determine who changed PageType, PageStatus, Area/Project/Topic relationships, and when.
 
Avoid storing critical classification changes only in mutable Cargo rows without corresponding revision/audit context.
 
---
 
== 33. Maintenance Scripts ==
 
Provide maintenance scripts for:
 
<pre>
Rebuild Cargo PKM tables
Validate all PARA metadata
Detect invalid status/type combinations
Detect dangling Area references
Detect dangling Project references
Detect dangling Topic references
Detect Area hierarchy cycles
Rebuild Wiki Health data
Repair/reconcile metadata after page moves
</pre>
 
Scripts should support dry-run mode where corrective behavior is possible.
 
---
 
== 34. Migration and Backward Compatibility ==
 
Standard Wiki pages shall not be forced into PARA metadata rules.
 
If a wiki changes from Standard to PARA mode, provide a migration/onboarding process rather than immediately invalidating all existing pages.
 
A migration condition such as '''Needs Classification''' should be a workflow/report state rather than necessarily a new PageStatus.
 
If a PARA Wiki changes to Standard mode, preserve existing structured metadata unless an administrator explicitly removes it.
 
---
 
== 35. Explicit Non-Goals for Version 1 ==
 
Unless separately approved, version 1 does not include:
 
<pre>
Custom user-defined PageTypes
Custom user-defined PageStatuses
ParentProject hierarchy
Automatic dynamic Area inheritance from Projects
AI-based automatic classification
Automatic Topic ontology generation
Security/ACL implementation based on PARA properties
Complex Topic-to-Topic ontology
Goal as a seventh PageType
Capture inbox implementation
Gamification beyond Wiki Health warnings/counts
</pre>
 
The architecture should not unnecessarily prevent these future capabilities.
 
---
 
== 36. Acceptance Criteria ==
 
=== Scenario A: Create top-level Area ===
 
Create Hobbies with PageType=Area, PageStatus=Active, ParentArea=NULL.
 
Expected: save succeeds, Hobbies appears in Area selectors, and Hobbies appears under Top-Level Areas.
 
=== Scenario B: Create child Area ===
 
Create Photography with PageType=Area, PageStatus=Active, ParentArea=Hobbies.
 
Expected: save succeeds; hierarchy shows Hobbies -> Photography; Photography appears in RelatedAreas selectors; Photography has no RelatedAreas value.
 
=== Scenario C: Prevent invalid Area metadata ===
 
Attempt to save Photography as Area with RelatedAreas=Hobbies.
 
Expected: save rejected and user instructed to use ParentArea.
 
=== Scenario D: Study with multiple relationships ===
 
Create Intro to Python as Study/Active with Areas Learning and Career, Project Complete course on Python, and Topics Programming and Python.
 
Expected: all relationships persist and query correctly.
 
=== Scenario E: Project Area defaulting ===
 
Plan Italy vacation has Areas Travel & Vacations and Family. Assign it to Hotels in Rome.
 
Expected: both Areas are initially added. User may remove Family before saving. Later changes to Project Areas do not modify Hotels in Rome automatically.
 
=== Scenario F: Archive Area ===
 
Archive Photography.
 
Expected: existing references remain; it disappears from default picker; Include archived Areas reveals it; direct access still works.
 
=== Scenario G: Unclassified page ===
 
Create Resource with no Area, Project, or Topic.
 
Expected: save succeeds; warning appears; Wiki Health count increases; page appears in Unclassified list.
 
=== Scenario H: Invalid status ===
 
Attempt Resource + Inception.
 
Expected: save rejected.
 
=== Scenario I: Area cycle ===
 
Attempt Hobbies.ParentArea=Photography while Photography.ParentArea=Hobbies.
 
Expected: save rejected with clear cycle error.
 
=== Scenario J: Topic behavior ===
 
Create Topic:Python, assign it to several pages, then archive it.
 
Expected: Topic hub lists associated pages; active selector includes it before archive; default selector excludes it after archive; existing references remain intact.
 
---
 
== 37. Open Design Questions ==
 
The developer/coding AI shall not invent final behavior for these items without product approval:
 
# Exact type-specific metadata fields for each PageType.
# Exact topic-specific metadata definition format.
# Whether Topic pages may themselves be assigned RelatedTopics.
# Whether Area pages may have Topics and/or RelatedProjects. Current recommendation: yes.
# Whether Project pages may have RelatedTopics. Current recommendation: yes.
# Exact VisualEditor integration approach.
# Whether classification metadata is stored in wikitext templates, a revision-backed slot/content model, or another revision-backed mechanism in addition to Cargo.
# Whether Wiki Mode is fixed at creation or can later be changed by an administrator.
# Whether a separate EntityType/schema-classification mechanism should eventually exist alongside Topics.
# Whether starter content is installed by extension code, Page Exchange packages, XML import, or another mechanism.
 
---
 
== 38. Recommended Implementation Order ==
 
Phase 1: Wiki Mode, PageType, PageStatus, Cargo table, basic metadata UI, validation.
 
Phase 2: Areas, ParentArea, RelatedAreas, hierarchy.
 
Phase 3: Projects, RelatedProjects, Project-to-Area default copying.
 
Phase 4: Topic namespace, Topic table, RelatedTopics, Topic hub pages.
 
Phase 5: Wiki Health dashboard, unclassified warnings, archive filtering.
 
Phase 6: starter-page onboarding, type-specific metadata framework, topic-specific metadata framework, API, and maintenance tools.
 
Each phase should include automated tests before proceeding.
 
---
 
== 39. Testing Requirements ==
 
Automated tests shall cover at least:
 
<pre>
PageType validation
PageStatus validation
status/type compatibility
ParentArea validation
Area cycle detection
Area selector filtering
Project selector filtering
Topic selector filtering
RelatedAreas list persistence
RelatedProjects list persistence
RelatedTopics list persistence
Project Area default copying
archived object behavior
unclassified detection
permissions-aware query output
page rename handling
page deletion/dangling-reference detection
API validation
</pre>
 
Use MediaWiki-supported unit/integration test frameworks appropriate to the installed version.
 
---
 
== 40. Coding Standards ==
 
The implementation shall follow MediaWiki extension conventions, use namespaced PHP classes, avoid deprecated APIs, use dependency injection where supported, validate on the server, escape user output, respect CSRF protection, respect MediaWiki permissions, document configuration/schema, provide upgrade logic for schema changes, and include automated tests for core business rules.
 
Avoid duplicating business rules independently in PHP and JavaScript where a server-side source of truth is practical.
 
---
 
== 41. Naming Standard ==
 
Canonical internal names:
 
<pre>
WikiMode
PageType
PageStatus
ParentArea
RelatedAreas
RelatedProjects
RelatedTopics
TopicName
TopicStatus
</pre>
 
Recommended user-facing labels:
 
<pre>
Wiki Mode
Type
Status
Parent Area
Related Areas
Related Projects
Topics
</pre>
 
Avoid underscores such as <code>Page_Type</code> unless required by a specific external convention. Avoid numbered relationship properties.
 
---
 
== 42. Summary of Core Business Rules ==
 
<pre>
Every PARA knowledge page:
    exactly one PageType
    exactly one valid PageStatus
 
If PageType = Area:
    zero or one ParentArea
    no RelatedAreas
 
If PageType != Area:
    no ParentArea
    zero or more RelatedAreas
 
Any normal page:
    zero or more RelatedProjects
    zero or more RelatedTopics
 
Topics:
    first-class classification objects
    not PageTypes
    recommended dedicated namespace
 
Archived:
    lifecycle state
    not security state
 
Project Area behavior:
    defaults copied at assignment time
    not permanently inherited
 
Unclassified:
    warning/report condition
    not a save-blocking error
</pre>
 
This model shall be treated as the implementation source of truth unless superseded by a later approved specification.
 
== Dynamic Hub Pages and Navigation ==
 
=== Purpose ===
 
Areas, Projects, and Topics shall function as navigational hubs in addition to storing user-authored content.
 
The system-generated relationship information shall be derived from structured metadata and shall not require the user to manually maintain lists of related pages.
 
The implementation should use one generalized '''Hub Page''' subsystem rather than separate unrelated implementations for Areas, Projects, and Topics.
 
=== Hub Page Types ===
 
The Hub Page subsystem shall apply to:
 
* pages whose <code>PageType=Area</code>
* pages whose <code>PageType=Project</code>
* pages in the <code>Topic:</code> namespace
 
The relationship used to populate the dynamic page list depends on the hub type:
 
{| class="wikitable"
! Hub type !! Relationship query
|-
| Area || Pages whose <code>RelatedAreas</code> contains the current Area
|-
| Project || Pages whose <code>RelatedProjects</code> contains the current Project
|-
| Topic || Pages whose <code>RelatedTopics</code> contains the current Topic
|}
 
=== Hub Page Layout ===
 
The rendered page should conceptually contain:
 
<pre>
Page title
Editable introductory content
System-generated hub section
Optional editable additional content
</pre>
 
The generated section shall not be directly editable and shall not be saved as ordinary wikitext.
 
Preferred long-term architecture:
 
<pre>
main revision-backed content slot
system-generated hub component
secondary revision-backed content slot (optional lower content)
</pre>
 
Before implementing a secondary slot, verify compatibility with the installed MediaWiki version and VisualEditor. If this materially increases version 1 complexity, version 1 may append the generated hub after the main editable content and defer lower editable content.
 
=== Area Hub Pages ===
 
An Area page shall automatically display:
 
* its Parent Area, when one exists
* its immediate child Areas
* pages directly associated with the Area
* sorting controls
 
Child Areas are derived from:
 
<pre>
ParentArea = current Area
</pre>
 
Directly associated pages are derived from:
 
<pre>
RelatedAreas HOLDS current Area
</pre>
 
Direct relationships shall be the default. Descendant content may optionally be included through a control such as "Include pages from sub-areas". Descendant inclusion shall be computed from the hierarchy; ancestor Areas shall not be redundantly written into RelatedAreas.
 
=== Project Hub Pages ===
 
A Project page shall automatically display:
 
* Project metadata
* Related Areas
* pages whose <code>RelatedProjects</code> contains the current Project
* sorting controls
 
Project-specific metadata such as target date, completion date, progress, or outcome may be displayed when implemented.
 
=== Topic Hub Pages ===
 
A Topic page shall automatically display:
 
* user-authored Topic description
* pages whose <code>RelatedTopics</code> contains the current Topic
* sorting controls
* optional derived counts grouped by PageType
 
The counts and lists shall be dynamically derived and not manually maintained.
 
=== Hub List Sorting ===
 
Every generated relationship list shall support:
 
* Page Name
* Creation Date
* Last Edit Date
 
The query layer shall support ascending and descending order.
 
Recommended user-facing choices:
 
<pre>
Name A-Z
Name Z-A
Newest Created
Oldest Created
Recently Updated
Least Recently Updated
</pre>
 
Default: <code>Name A-Z</code>, unless configured otherwise.
 
=== Hub List Filtering ===
 
The architecture shall support future filters including:
 
* PageStatus
* PageType
* direct relationships versus descendant Area relationships
 
Archived content should be excluded from normal hub lists by default where appropriate and exposed through an explicit filter.
 
=== Page Creation and Last-Edit Dates ===
 
MediaWiki revision history shall remain authoritative for creation and last-edit timestamps.
 
For efficient querying and sorting, the application may maintain indexed/cached values:
 
<pre>
CreatedAt
UpdatedAt
</pre>
 
The implementation shall document how they are populated and refreshed and should avoid querying the earliest revision of every result during ordinary rendering.
 
=== Permissions ===
 
All generated Hub content shall respect MediaWiki read permissions and future sharing/ACL rules.
 
A viewer shall not learn the title, existence, metadata, or count contribution of a page they cannot view.
 
This applies to relationship lists, child Areas, counts, filters, autocomplete, Topic breakdowns, Main Page lists, and APIs.
 
=== Pagination and Performance ===
 
Generated lists shall support pagination and server-side sorting for large result sets.
 
The implementation should use indexed query fields, avoid full-table scans, use MediaWiki caching where appropriate, and invalidate/refresh cached output when relevant relationships or metadata change.
 
The subsystem should remain practical for hubs containing thousands of related pages.
 
=== Empty States ===
 
Hub pages shall render useful empty-state messages, such as:
 
<pre>
No pages are currently associated with this Area.
No pages are currently assigned to this Project.
No pages currently use this Topic.
</pre>
 
== Main Page Dashboard ==
 
In PARA Wiki mode, the Main Page shall provide generated navigation in addition to user-configurable introductory content.
 
At minimum it shall display:
 
* a hierarchical list of active Areas
* Active Projects
 
=== Area Hierarchy ===
 
Top-level Areas are:
 
<pre>
PageType = Area
PageStatus = Active
ParentArea = NULL
</pre>
 
Each top-level Area shall display active child Areas recursively or to a configurable display depth.
 
The hierarchy shall be derived from <code>ParentArea</code>, never manually maintained.
 
Archived Areas shall be excluded by default.
 
=== Active Projects ===
 
The Main Page shall display:
 
<pre>
PageType = Project
PageStatus = Active
</pre>
 
Each title shall link to its Project hub page.
 
Provide a link to an All Projects view that can include Inception and Archived Projects.
 
The initial Main Page should remain concise; recently edited pages, unclassified counts, and Wiki Health summaries may be added later.
 
== System Index Pages ==
 
The extension shall provide generated index views for:
 
* All Areas
* All Projects
* All Topics
* Wiki Health
* Unclassified Pages
 
Where practical these should be MediaWiki Special pages rather than editable normal pages.
 
Recommended routes:
 
<pre>
Special:Areas
Special:Projects
Special:Topics
Special:WikiHealth
Special:UnclassifiedPages
</pre>
 
=== All Areas ===
 
Support hierarchical display, Active/Archived filtering, links to Area hubs, and optional direct/descendant page counts.
 
=== All Projects ===
 
Support PageStatus filtering, Area filtering, sorting by Page Name/Creation Date/Last Edit Date, and links to Project hubs.
 
=== All Topics ===
 
At minimum show Topic name, link, Active/Archived filtering, and count of accessible pages using the Topic.
 
Recommended sorting:
 
<pre>
Name
Number of Pages
Recently Used
Creation Date
Last Edit Date
</pre>
 
Potential future maintenance views include unused Topics, Topics without descriptions, archived Topics, and possible duplicates.
 
== Hub Subsystem Technical Architecture ==
 
Implement a generalized service rather than independent Cargo queries embedded in templates.
 
Recommended conceptual components:
 
{| class="wikitable"
! Component !! Responsibility
|-
| <code>HubService</code> || Determine whether the current page is a Hub and assemble its view model.
|-
| <code>HubQueryService</code> || Retrieve related pages using the appropriate relationship.
|-
| <code>HubRenderer</code> || Render generated Hub sections.
|-
| <code>AreaHierarchyService</code> || Resolve parents, children, descendants, and cycle-safe traversal.
|-
| <code>HubSort</code> || Validate and translate supported sort modes.
|-
| <code>HubFilter</code> || Validate and apply supported filters.
|}
 
Templates may assist presentation, but relationship selection, permissions, hierarchy traversal, sorting, and validation shall reside in extension code.
 
Relationship mapping:
 
<pre>
Area    -> RelatedAreas
Project -> RelatedProjects
Topic  -> RelatedTopics
</pre>
 
Adding a future Hub-capable object should not require rewriting the subsystem.
 
== Additional API Requirements for Hubs and Indexes ==
 
The API shall additionally support operations equivalent to:
 
<pre>
Get hub metadata
List pages related to an Area
List pages related to a Project
List pages related to a Topic
List child Areas
List Area descendants
List Area hierarchy
List Projects by status
List Topics
</pre>
 
List operations shall support pagination and, where relevant:
 
<pre>
sort
direction
status
pageType
includeArchived
includeDescendants
limit
continuation
</pre>
 
Exact names shall follow MediaWiki/API conventions.
 
== Additional Acceptance Criteria for Dynamic Hubs ==
 
=== Scenario K: Area Hub ===
 
Given Personal as an Active Area and several pages with <code>RelatedAreas=Personal</code>:
 
* Personal automatically lists those pages.
* no manually maintained list is required
* changing RelatedAreas updates Hub membership
* generated list is not editable as ordinary page text
 
=== Scenario L: Hub Sorting ===
 
Given related pages with different names, creation dates, and edit dates:
 
* sort alphabetically
* sort by creation date
* sort by last edit date
* sorting does not modify metadata
* sorting works with pagination
 
=== Scenario M: Area Hierarchy ===
 
Given Photography and Cooking with <code>ParentArea=Hobbies</code>:
 
* Hobbies displays them as children
* each child displays Hobbies as parent
* hierarchy is generated from ParentArea
 
=== Scenario N: Direct Area Relationships ===
 
Given <code>Canon EOS R10</code> with <code>RelatedAreas=Photography</code>:
 
* it appears in Photography's direct list
* it does not appear in Hobbies' direct list solely because Photography is beneath Hobbies
* a descendant-inclusive view may include it
 
=== Scenario O: Project Hub ===
 
Given <code>Hotels in Rome</code> with <code>RelatedProjects=Plan Italy vacation</code>:
 
* Plan Italy vacation automatically lists Hotels in Rome
* Project Areas are displayed
* generated list is not directly editable
 
=== Scenario P: Topic Hub ===
 
Given <code>Topic:Python</code> and multiple pages using it:
 
* Topic:Python lists accessible associated pages
* it may display derived PageType counts
* archiving the Topic does not destroy relationships
 
=== Scenario Q: Main Page Area Tree ===
 
* active top-level Areas render hierarchically
* child Areas appear beneath parents
* archived Areas are excluded by default
* links point to Area hubs
 
=== Scenario R: Main Page Projects ===
 
* Active Projects display by default
* Inception and Archived Projects do not
* All Projects view can expose other statuses
 
=== Scenario S: Topics Index ===
 
* Special:Topics lists accessible Topics
* Topics can be sorted by name
* usage counts respect permissions
* archived Topics can be filtered
 
=== Scenario T: Hub Permissions ===
 
* inaccessible related pages are not displayed
* inaccessible titles do not contribute to exposed counts
* API behavior matches rendered-page behavior
 
== Additional Open Design Questions ==
 
# Whether version 1 supports editable content both above and below the generated Hub section, or initially only before it.
# Whether a secondary MediaWiki content slot provides acceptable VisualEditor behavior.
# Whether descendant-Area inclusion ships in version 1 or is deferred.
# Whether Hub sort/filter preferences are temporary, per-user, or per-Hub.
# Exact default pagination size.
# Whether Topic PageType breakdown counts ship in version 1.
# Whether Main Page dashboard sections are configurable/reorderable in version 1.
# Whether system indexes also expose transcludable components in addition to Special pages.
Retrieved from "https://wiki.goalstriving.org/Requirements_and_Specifications"