Domain understanding

use-cases/task-manager/javascript/documentation.md

@@ -0,0 +1,146 @@
+# Exercise 1 Code Understanding
+
+## Language Used
+The code I have chosen is **JavaScript**.
+
+# Code Breakdown
+
+## Codebase
+
+There are 4 javascript files it appears.
+There seems to be an attempt at a backend by using module.export and the require key word and file paths but no official frameworks.
+
+## Initial Understanding
+### Organization
+- It appears app.js is the main file.
+- cli.js seems to convert the project into a usable command line interface by creating a program constant and using the commander library to create a command line interface.
+- models.js seems to be handeling the task management of the project
+- storage.js seems to be running where and how the project data is stored. It can also edit the stored data.
+
+### Frameworks and technologies
+- module exports
+- CLI tools/commander library
+- Task manager class
+- Engine uuidv4
+- File pathing
+
+### Main Components
+- CLI Tools
+- File pathing
+
+## Project Structure
+### Using Prompt
+*** My Prompt ***
+I'm a junior developer who just joined this project. I've read the README but still need help understanding the project structure and technology stack
+Here's my current understanding of the project:
+
+## Codebase
+
+There are 4 javascript files it appears.
+There seems to be an attempt at a backend by using module.export and the require key word and file paths but no official frameworks.
+
+## Initial Understanding
+### Organization
+- It appears app.js is the main file.
+- cli.js seems to convert the project into a usable command line interface by creating a program constant and using the commander library to create a command line interface.
+- models.js seems to be handeling the task management of the project
+- storage.js seems to be running where and how the project data is stored. It can also edit the stored data.
+
+### Frameworks and technologies
+- module exports
+- CLI tools/commander library
+- Task manager class
+- Engine uuidv4
+- File pathing
+
+### Main Components
+- CLI Tools
+- File pathing
+Project structure
+task-manager
+     --Java
+     --Javascript
+        --app.js
+        --cli.js
+        --models.js
+        --storage.js
+    --python
+We are only focussing on the JavaScript folder
+Configuration Files:
+None
+Could you:
+1. Validate my understanding and correct any misconceptions
+2. Identify additional key technologies, frameworks, and libraries used
+3. Explain what each main folder likely contains and its purpose
+4. Point out where the application entry points are located
+5. Suggest 3-5 specific questions I should ask my team to deepen my understanding
+After your explanation, could you suggest a small exploration exercise I could do to verify my understanding of the project structure?
+
+*** Claude Response ***
+1. Validating Your Understanding
+Your instincts are largely correct, with a few refinements:
+What you got right:
+
+app.js as the main entry point is a standard Node.js convention — good call.
+cli.js using Commander to expose a CLI is accurate. Commander is a well-established library for parsing command-line arguments and defining commands/flags.
+storage.js handling data persistence (read/write) is a sensible separation of concerns.
+models.js containing a Task management class is a classic MVC-style "model" layer.
+
+Misconceptions to correct:
+
+"An attempt at a backend" — module.exports and require are not signs of an incomplete or attempted backend. They are simply Node.js's built-in CommonJS module system, the standard way to split code across files in Node.js. This is intentional and complete, not a workaround.
+"No official frameworks" — this is likely a deliberate architectural choice. Many CLI tools are built as lightweight Node.js apps without Express or similar, because they don't serve HTTP traffic. The absence of a framework isn't a gap; it's appropriate for the tool's purpose.
+"Engine uuidv4" — UUIDv4 is not an engine. It's a small utility library for generating universally unique IDs (e.g. giving each task a unique identifier like f47ac10b-58cc...). Think of it as a helper, not a runtime.
+
+
+2. Key Technologies & Libraries
+Based on your description, here's the fuller picture:
+TechnologyRoleNode.jsThe JavaScript runtime — what actually executes the codeCommonJS (require/module.exports)Node's module system for splitting code across filesCommander.jsParses CLI arguments, defines commands and flagsuuid / uuidv4Generates unique IDs for each taskNode fs moduleAlmost certainly used in storage.js for reading/writing files to diskJSONLikely the storage format (a flat .json file acting as a simple database)
+
+3. What Each File Likely Does
+task-manager/
+└── Javascript/
+    ├── app.js       → Wires everything together. Imports the CLI and kicks off execution.
+    ├── cli.js       → Defines user-facing commands (e.g. `add`, `list`, `delete`).
+    │                  Uses Commander to parse what the user types in the terminal.
+    ├── models.js    → The Task class/object. Defines what a task looks like (id, title,
+    │                  status, etc.) and methods to operate on tasks.
+    └── storage.js   → Reads from and writes to a file on disk. Handles all persistence
+                       so the other files don't need to know *how* data is saved.
+The Java and Python folders likely contain parallel implementations of the same task manager — a common pattern for learning projects or polyglot codebases demonstrating the same app in multiple languages.
+
+4. Entry Points
+There are likely two entry points depending on how the app is used:
+
+app.js — the primary Node.js entry point, probably run via node app.js or referenced in a package.json "main" field.
+cli.js — may also be executable directly (e.g. node cli.js add "Buy milk"), or it's imported by app.js which delegates to it immediately.
+
+Check for a package.json — if it exists, the "bin" or "main" field will tell you the definitive entry point, and "scripts" will show you how the team actually runs it.
+
+5. Questions to Ask Your Team
+
+"Is there a package.json, and what does the scripts section look like?" — This reveals how the app is built, run, and tested, and whether there are dependencies you haven't seen yet.
+"Where is task data actually stored — a local JSON file, or something else?" — Understanding the storage target clarifies storage.js's full role.
+"Is this CLI tool meant to be installed globally (npm install -g) or run locally?" — This affects how users interact with it and how Commander is configured.
+"Are the Java and Python folders feature-equivalent to the JavaScript version, or are they experiments/stubs?" — Knowing this tells you whether cross-language consistency matters.
+"Are there any plans to add tests?" — Junior-friendly question that reveals team practices and gives you a contribution opportunity.
+
+
+Exploration Exercise
+Try this structured trace-through — no code changes, just reading:
+
+Start at app.js — identify every require() call. Draw a simple arrow diagram of what it imports.
+Open cli.js — find each .command() call in Commander. List the commands the app exposes (e.g. add, list, complete).
+Open models.js — find the class definition. List its properties (what fields does a Task have?) and its methods.
+Open storage.js — find where it reads and writes. What filename or path does it use? What format is the data?
+Try running it — if Node.js is installed, run node app.js or node cli.js --help and see if the Commander help output matches the commands you found in step 2.
+
+## Findings 
+### Misconceptions to correct:
+1. "An attempt at a backend" — module.exports and require are not signs of an incomplete or attempted backend. They are simply Node.js's built-in CommonJS module system, the standard way to split code across files in Node.js. This is intentional and complete, not a workaround.
+2. Engine uuidv4" — UUIDv4 is not an engine. It's a small utility library for generating universally unique IDs (e.g. giving each task a unique identifier like f47ac10b-58cc...). 
+### Final Resault
+1. My understanding of the project structure is mostly correct, with some refinements regarding the use of CommonJS modules and the role of uuidv4.
+2. Key technologies include Node.js, CommonJS modules, Commander.js for CLI parsing, uuid
+3. Each file has a clear purpose: app.js is the main entry point, cli.js defines the CLI commands, models.js defines the Task class, and storage.js handles data persistence.
+4. The main entry point is likely app.js, but cli.js may also be directly executable

use-cases/task-manager/javascript/domainModel.md

@@ -0,0 +1,190 @@
+# Exercise 3
+# Domain Model
+## Extract domain model from codebase
+### Core classes
+- TaskStorage
+- TaskManager
+- TaskPriority (enum for task priority levels)
+- TaskStatus (enum for task status)
+- Task class
+
+
+## Initial Understanding
+### Simple Diagram
+```mermaid
+classDiagram
+    TaskStorage <|-- TaskManager
+    TaskManager o-- Task
+    Task : +id
+    Task : +title
+    Task : +description
+    Task : +priority
+    Task : +status
+
+    flowchart LR
+       A[Task Class] --> B[TaskManager]
+       B --> C[TaskStorage]
+       C --> D(TaskPriority)
+       D --> E(TaskStatus)
+```
+1. The main Class A is the starting point
+2. Class A leads to B which is the TaskManager class that handles the logic of managing tasks
+3. TaskManager interacts with C (TaskStorage) which is responsible for data persistence
+4. Task C interacts with D and E which are enums for TaskPriority and TaskStatus respectively, defining the possible values for these properties in a task.
+
+## Prompts
+### Prompt Used
+I'd like you to act as a senior developer who deeply understands our codebase's domain model. I'm a junior developer trying to make sense of the business logic and domain concepts in this application
+Here's what I've found in the codebase:
+### Core classes
+- TaskStorage
+- TaskManager
+- TaskPriority (enum for task priority levels)
+- TaskStatus (enum for task status)
+- Task class
+### Simple Diagram
+```mermaid
+classDiagram
+    TaskStorage <|-- TaskManager
+    TaskManager o-- Task
+    Task : +id
+    Task : +title
+    Task : +description
+    Task : +priority
+    Task : +status
+
+    flowchart LR
+       A[Task Class] --> B[TaskManager]
+       B --> C[TaskStorage]
+       C --> D(TaskPriority)
+       D --> E(TaskStatus)
+```
+1. The main Class A is the starting point
+2. Class A leads to B which is the TaskManager class that handles the logic of managing tasks
+3. TaskManager interacts with C (TaskStorage) which is responsible for data persistence
+4. Task C interacts with D and E which are enums for TaskPriority and TaskStatus respectively, defining the possible values for these properties in a task.
+Could you, as a senior developer:
+1. Validate my current understanding, correcting any misconceptions
+2. Help me recognize the core domain concepts represented in this code
+3. Explain the relationships between these entities in business terms, not just technical relationships
+4. Clarify any domain-specific terminology or patterns I might be missing
+5. Help me connect these models to actual user-facing features or business processes
+
+Then, please ask me 3-5 questions that would test my understanding of this domain model. These should be questions that make me think about the business logic, not just the code syntax.
+
+Finally, suggest a simple diagram I could sketch to visualize these relationships that would help solidify my understanding.
+
+### Prompt Response
+1. Validation & Corrections ✅ / ⚠️
+What You Got Right:
+
+✅ Task is the core entity
+✅ TaskManager orchestrates business logic
+✅ TaskStorage handles persistence
+✅ TaskPriority and TaskStatus are domain constraints
+Critical Misconceptions to Fix:
+
+⚠️ Relationship Direction: Your diagram shows TaskStorage <|-- TaskManager (inheritance with TaskStorage being the parent). This is backwards.
+
+Reality: TaskManager depends on TaskStorage (composition, not inheritance)
+Better notation: TaskManager --> TaskStorage (TaskManager uses TaskStorage)
+Why it matters: This is about dependency flow, not class hierarchies. TaskManager is the high-level layer that delegates to TaskStorage.
+⚠️ Missing Domain Concepts: You're missing critical attributes that represent business requirements:
+
+tags - How users organize/categorize tasks
+dueDate, createdAt, updatedAt, completedAt - Temporal tracking (when things happen)
+isOverdue() - Business logic (a task is "overdue" when it's past due date AND not done)
+markAsDone() - Explicit state transition with side effects (sets completedAt automatically)
+2. Core Domain Concepts (Business Language)
+Let me translate the code into real business/product thinking:
+
+Code Concept	Business Concept	Why It Matters
+Task	A unit of work	Everything revolves around this—it's what users care about
+Priority (1-4)	Urgency signal	Helps teams decide what to tackle first
+Status (TODO→IN_PROGRESS→REVIEW→DONE)	Workflow state	Models the journey of work through a team's process
+Tags	Flexible categorization	Users can organize by project, team, feature, bug type, etc.
+dueDate	Deadline	Creates accountability and urgency
+isOverdue()	Business rule	A task is only "overdue" if it has a deadline AND hasn't been completed—this is critical logic
+TaskManager	Task coordinator	The "brains" of the system—validates input, applies rules
+TaskStorage	Record keeper	Like a filing cabinet—doesn't make decisions, just stores/retrieves
+3. Relationships in Business Terms
+Real example from the code:
+
+This shows layered architecture:
+
+Presentation Layer (cli.js): "What can the user do?"
+Business Logic (app.js): "What are the rules?"
+Data Layer (storage.js): "How do we remember?"
+4. Domain-Specific Patterns You Should Know
+Pattern 1: Value Objects (TaskPriority, TaskStatus)
+
+Pattern 2: Domain Logic Living in the Entity
+
+Pattern 3: State Transitions
+
+Pattern 4: Lazy vs. Active Properties
+
+5. Connecting to User-Facing Features
+Here's how the domain model enables real features:
+
+User Goal	Feature	Domain Concepts Used
+"Show me what to do today"	list with filters	Task.status, Task.dueDate
+"I'm working on this"	status <id> in_progress	TaskStatus enum, Task.update()
+"This is urgent"	priority <id> 4	TaskPriority enum, Task.priority
+"Mark it done when complete"	status <id> done	Task.markAsDone(), Task.completedAt
+"Show stats"	stats	TaskStorage aggregations (getAllTasks, getTasksByStatus)
+"Which tasks are late?"	list --overdue	Task.isOverdue() business logic
+
+📊 Improved Domain Model Diagram
+Here's a better visualization (corrects your relationship directions):
+
+Key differences from your diagram:
+
+TaskManager --> TaskStorage (dependency arrow, not inheritance)
+Added temporal tracking (createdAt, updatedAt, completedAt)
+Added tags and methods that represent business logic
+TaskStatus and TaskPriority are shown as enumerations
+Added method signatures so you see what each layer is responsible for
+💡 Mental Model to Carry Forward
+Think of it like a restaurant kitchen:
+
+Task = A plate that needs to be prepared (the product)
+TaskManager = Head chef (makes decisions, ensures quality, follows recipes)
+TaskStorage = Pantry (remembers ingredients, keeps organized records)
+TaskStatus = Stage of the order (ordered → cooking → plating → served)
+Priority = How urgently the order should be cooked
+Understanding these business concepts makes it much easier to extend the system—you'll know where logic belongs and what constraints you need to maintain.
+
+### Prompt Questions
+Q1: The "Overdue" Concept
+
+A task with dueDate = May 20 and status = DONE (completed on May 18). Is it overdue? Check the isOverdue() method in the code. Why does the business logic check this.status !== TaskStatus.DONE?
+
+Q2: Tags Design
+
+Why do you think tags are stored as an array tags: [] rather than a single string? What business scenarios would multiple tags enable?
+
+Q3: When Does completedAt Get Set?
+
+In the code, completedAt only gets set when markAsDone() is called. What happens if someone calls updateTaskStatus(taskId, TaskStatus.DONE) directly instead? Is this a bug or intentional? (Hint: look at the code in app.js)
+
+Q4: Data Flow for "Show Me Overdue Tasks"
+
+If a user runs list --overdue, trace the path through all three layers. Where does each layer add value? What would break if you removed TaskManager and called TaskStorage directly from CLI?
+
+Q5: Statistics Aggregation
+
+The getStatistics() method in TaskManager counts tasks by status and priority. Why is this logic in TaskManager rather than in TaskStorage? What business decisions does this enable at the management level?
+
+## Testing Knowledge
+### Questions
+**Q1**
+No it is not overdue, the completed date is before due date and status is marked as done. The isOverdue() method checks if the status is not DONE because a task that is already completed cannot be overdue, regardless of its due date.
+**Q2**
+Tags are stored in a array to allow for multiple tags to be associated with a single task. This enables users to categorize and organize tasks in more flexible ways, such as by project, team, feature, or bug type.
+**Q3**
+This is likely intentional. The markAsDone() method not only sets the status to DONE but also records the completedAt timestamp. If someone calls updateTaskStatus(taskId, TaskStatus.DONE) directly, it would change the status but would not set the completedAt timestamp, which could lead to incomplete data about when tasks were actually completed.
+**Q4**
+When a user runs list --overdue, the CLI layer (cli.js) would parse the command and recognize the --overdue flag. It would then call a method in TaskManager (app.js) that retrieves all tasks from TaskStorage and applies the isOverdue() logic to filter out only those tasks that are overdue. If you removed TaskManager and called TaskStorage directly from CLI, you would lose the business logic encapsulated in TaskManager, such as filtering for overdue tasks, and you would have to implement that logic in the CLI layer, which is not ideal for separation of concerns.
+**Q5**
+The getStatistics() method is in TaskManager rather than TaskStorage because it involves business logic that aggregates and interprets the raw data of tasks. TaskStorage's responsibility is to store and retrieve data, while TaskManager's role is to apply business rules and provide meaningful insights. By keeping this logic in TaskManager, it allows for more complex calculations and decision-making based on the task data, which can inform management decisions about resource allocation, project progress, and areas that may need attention.

use-cases/task-manager/javascript/finalDiscussion.md

@@ -0,0 +1,11 @@
+# Final Discussion
+## Approach to understanding codebase
+I found it quite fun to read through a code base and gaining a my own perspective on what it is about adn the  using the prompts I leant to see what I missed and what I got tight
+## Challenges
+My main problem was running out of prompts as my chatbot had limited propmts. I created a GitHub with the email I was given for the course so I had a fresh account for prompts
+## Most useful prompts
+Prompt 1 was the most helpful as I could properly understand the logic of the project
+## For future
+I would use the prompt to identify what the local imported libraries are for and what they do as I had a hard time understanding the commander library and how it worked with the cli.js file.
+## Additional tools
+I would use a code editor with better search capabilities and a better terminal to run the project and test my changes. I also would have used a better chatbot with more prompts to ask about the project and my changes.