Design a Python Task Manager

Plan a layered Python task manager with SQLite, validation, and tests.

Introduction

30 Second Summary

A request like “make a task manager” leaves dozens of hidden decisions about behavior, boundaries, and failure handling. Without a shared plan, those decisions surface during coding as rework.

In this project, you will turn the TaskTrack brief into a committed design pack with testable acceptance criteria. You will map five pages onto a layered architecture, define the data rules, plan the tests, and organize the remaining work into reviewable stages.

What You'll Build

Picture a developer opening your repository and tracing any TaskTrack action from a testable requirement through the planned code layers to storage.

By the end of this project, you'll have:

  • A reviewer-ready requirements pack covering create, read, update, delete, search, filter, sort, and analytics workflows across all five pages.
  • A layered architecture map that traces page actions through service and repository boundaries into SQLite.
  • An implementation-ready plan defining the task schema, validation boundaries, test strategy, and delivery stages.
  • Secret Mission: Add a failure-mode matrix that connects realistic validation and database errors to user feedback, rollback decisions, and test coverage.

Are there any prerequisites?

You need a Windows computer with Python 3.11 or newer, Git, a code editor, Streamlit, pandas, and pytest available. This stage creates local documentation only, so you will not install packages or build the application yet.

Before We Start

Before any files take shape, lock in the user problem that TaskTrack solves. This one-sentence statement will anchor every requirement and architecture decision.

Set Up the Design Workspace

TaskTrack has a clear user problem. The architecture decisions that follow need a clean Git repository.

This step confirms the existing Windows PowerShell, Git, and Python tools before creating that reviewable home. You will not install or upgrade any packages.

In this step, get ready to:
  • Confirm the existing development tools.
  • Create the complete TaskTrack workspace.
  • Initialize the local Git repository.
Confirm the existing tools

Version checks confirm that the tools required for this design stage are available. They also preserve the current environment because neither command changes your installation.

  • Press the Windows key to open Windows search.
  • Type Windows PowerShell into the search field.
  • Press Enter to open Windows PowerShell.
  • Confirm both tools by running these commands:
git --version
python --version

What do these checks prove?

  • The git --version command confirms that Git is available.
  • The python --version command confirms which Python version Windows PowerShell uses.
  • Both commands only display information about the existing environment.

You should see a Git version number followed by a Python version number. The Python output must show 3.11 or newer.

A version check did not work?

  • Check that you opened Windows PowerShell instead of a browser search result.
  • Stop before installing or upgrading anything because this stage uses your confirmed environment.

Help me diagnose a Git or Python version check that fails in Windows PowerShell. You can also share the non-sensitive output with the NextWork community.

Create the design workspace

A predictable folder structure keeps each design decision in the document where it belongs. The empty files establish that structure before requirements writing begins.

  • Move to your Desktop by running this command:
Set-Location -Path "$env:USERPROFILE\Desktop"

Why start on the Desktop?

The Set-Location command makes your Desktop the active PowerShell location. This keeps the new TaskTrack folder easy to find.

  • Create the complete TaskTrack folder structure by running these commands:
New-Item -ItemType "Directory" -Path "TaskTrack"
Set-Location -Path "TaskTrack"
New-Item -ItemType "Directory" -Path "docs"
New-Item -ItemType "File" -Path "README.md"
New-Item -ItemType "File" -Path "docs\requirements.md"
New-Item -ItemType "File" -Path "docs\architecture.md"
New-Item -ItemType "File" -Path "docs\test-plan.md"
New-Item -ItemType "File" -Path "docs\implementation-plan.md"

What does this workspace contain?

  • The first command creates the TaskTrack folder.
  • The Set-Location command moves PowerShell into that folder.
  • The next command creates the docs directory.
  • The remaining commands create five empty design documents.
  • Press the Windows key to open Windows search.
  • Type the name of the code editor you confirmed before this project.
  • Press Enter to open the code editor.
  • Use the editor's folder-opening option to open the TaskTrack folder from your Desktop.

You should see README.md at the top level. You should also see four empty documents inside docs.

Missing a design document?

  • Check that the editor opened TaskTrack instead of your Desktop.
  • Compare every file name with the workspace checklist below.

Help me find a missing TaskTrack workspace file.

✔️ Awesome, I've got everything!

Great. Your code editor now has the complete empty design workspace open.

ⓧ I'd like to double check the full workspace

Compare your open TaskTrack folder with this structure.

  • Confirm that README.md is an empty file at the repository root.
  • Confirm that docs\requirements.md is an empty requirements document.
  • Confirm that docs\architecture.md is an empty architecture document.
  • Confirm that docs\test-plan.md is an empty test-plan document.
  • Confirm that docs\implementation-plan.md is an empty implementation-plan document.
Initialize and inspect the repository

Git needs repository metadata before it can report changes in the workspace. Initializing at the TaskTrack root keeps every design document under the same history.

  • Switch back to the Windows PowerShell window from earlier.
  • Initialize the TaskTrack repository by running this command:
git init

What does this command do?

The git init command creates an empty Git repository in the current TaskTrack folder. It does not create a commit.

You should see confirmation that Git initialized an empty repository inside TaskTrack.

Before you inspect the repository, predict which paths Git will list as untracked.

  • Inspect the new repository by running this command:
git status

What does this status prove?

The git status command reports paths that Git can see but has not tracked. This confirms that repository initialization happened in the correct folder.

Git should report README.md and the docs directory as untracked content. The status should also indicate that no commit exists yet.

Do the untracked paths look different?

  • Check that the PowerShell prompt ends with the TaskTrack folder name.
  • Check that README.md sits beside the docs directory.
  • Check that you ran git init from the TaskTrack root.

Help me diagnose an unexpected TaskTrack Git status.

That is the workspace foundation complete. Git can now review every design decision from this point onward.

Your reviewable design workspace is ready. Next, you will turn TaskTrack's feature list into scoped acceptance criteria.

Define Acceptance Criteria

Your design workspace is ready. The empty requirements document now needs to become the product contract for TaskTrack.

A feature list such as "search tasks" leaves too much room for interpretation. Acceptance criteria remove that ambiguity by defining the starting context, the user action, and the observable result.

In this step, get ready to:
  • Define the local-only scope plus the five TaskTrack pages.
  • Write Given-When-Then criteria for every primary workflow.
  • Set explicit rules for every task field.
Define the user, scope, and five pages

Scope control protects TaskTrack from growing beyond its original purpose. A clear boundary also tells reviewers which missing features are deliberate.

  • Switch back to docs\requirements.md in the code editor from earlier.
  • Write an opening User and Scope section beneath a TaskTrack Requirements title using the Step 0 user statement plus the local-only boundary.
  • Save docs\requirements.md.

You should now see that TaskTrack serves individuals who want a private task manager that runs locally without cloud services.

  • Add a Pages section containing five entries. Use Dashboard for the starting overview. Use Add Task for task creation. Use View Tasks for browsing tasks. Use Manage Tasks for updates plus deletion. Use Analytics for statistics plus charts.
  • Save docs\requirements.md.

Good progress. The product now has five visible destinations with a distinct purpose for each one.

  • Add a Primary Workflows section listing task creation, viewing, search, filtering, sorting, updating, deletion, statistics, and charts.
  • Save docs\requirements.md.

You should see all nine workflows grouped in one place. This list becomes the index for the criteria you write next.

  • Add a Non-Goals section that excludes authentication, external APIs, and cloud deployment from this stage.
  • Save docs\requirements.md.

The requirements now state what TaskTrack covers. They also prevent later work from quietly expanding the agreed Python stack.

Write testable workflow outcomes

Each primary workflow needs a result that another person can verify. You will use Given-When-Then to connect the starting state to one user action plus one observable outcome.

How Given, When, and Then Work

  • Given defines the state of TaskTrack before the action begins.
  • When names the single action performed by the user.
  • Then describes the result that the user or tester can observe.
  • Add a Task Lifecycle Criteria section with four criteria. For creation, start with a user on Add Task who has entered valid task details. Use saving the task as the action. Make storage plus visibility in the task list the result. For viewing, start with existing tasks. Use opening View Tasks as the action. Make all stored tasks plus their fields the result. For updating, start with an existing task selected in Manage Tasks. Use saving valid changes as the action. Make the persisted values visible in the task list. For deletion, start with an existing task selected in Manage Tasks. Use deleting that task as the action. Make its removal from the task list the result.
  • Save docs\requirements.md.

You should see four separate criteria covering create, view, update, and delete. Each criterion should contain an explicit Given, When, and Then statement.

  • Add a Finding Tasks Criteria section with three criteria. For search, start with multiple tasks in View Tasks. Use entering search text as the action. Make tasks with matching titles or descriptions the only visible results. For filtering, start with tasks that have different priorities or statuses. Use selecting a filter as the action. Make only matching tasks visible. For sorting, start with multiple visible tasks. Use selecting a sort option as the action. Make the displayed order follow the selected field plus direction.
  • Save docs\requirements.md.

You should now see criteria for search, filtering, and sorting. Their Then statements describe changes a tester can observe in the displayed task list.

  • Add an Insights Criteria section with two criteria. For statistics, start with stored tasks across different statuses or priorities. Use opening Analytics as the action. Make the task totals plus grouped counts visible. For charts, start with task data available to summarize. Use opening Analytics as the action. Make charts for the grouped task data visible.
  • Save docs\requirements.md.

All nine primary workflows now have testable outcomes. The criteria describe what success looks like without prescribing the later implementation.

Lock down task field rules

Field rules close the gaps left by workflow criteria. They define which values are required plus which defaults TaskTrack supplies.

  • Add a Task Field Rules section. Define title as required after trimming whitespace. Define description as optional. Define deadline as optional. Limit priority to Low, Medium, or High with Medium as the default. Limit status to To Do, In Progress, or Done with To Do as the default.
  • Save docs\requirements.md.

You should see one rule for every task field. The allowed priority plus status values now give later validation and database work a fixed target.

Before you check, which of the nine workflows do you think is easiest to leave vague?

  • Return to the top of docs\requirements.md in your code editor.
  • Confirm the scope names Dashboard, Add Task, View Tasks, Manage Tasks, and Analytics.
  • Check that create, view, search, filter, sort, update, delete, statistics, and charts each have Given, When, and Then statements.
  • Verify that the task field rules include every required value plus both defaults.

You should see a local-only product scope, five named pages, nine testable workflows, three explicit non-goals, and complete task field rules. That is a strong design milestone because another person can now review TaskTrack before implementation begins.

Your requirements document now defines what TaskTrack must do plus where its boundaries sit. Next, you will test a single-file architecture against these requirements and expose the coupling it creates.

Audit the Single-File Design

Your requirements now define the five TaskTrack pages. They also define the behavior each workflow must deliver.

A single-file Streamlit plan can look efficient until one change touches widgets, validation, SQLite queries, analytics, and error handling. This step makes that coupling visible before you choose the final structure.

In this step, get ready to:
  • Document a deliberately naive design where app.py owns every responsibility.
  • Audit the impact of three realistic development changes.
  • Record why the single-file design prevents independent testing and change.
Sketch the deliberately naive design

The first design intentionally concentrates TaskTrack inside app.py. Its responsibility map gives you something concrete to challenge.

  • Switch back to docs\architecture.md in the confirmed code editor.
  • Add the naive design by pasting this content into the empty document:
# TaskTrack Architecture

## Deliberately Naive Single-File Design

The first design places the entire TaskTrack application in `app.py`.

| Responsibility | What `app.py` owns |
| --- | --- |
| Page routing | Selects and displays all five pages. |
| Streamlit widgets | Creates forms, filters, tables, metrics, and charts. |
| Validation | Checks titles, deadlines, priorities, and statuses. |
| SQLite SQL | Opens connections and runs create, read, update, and delete statements. |
| Analytics | Calculates task totals and chart-ready summaries. |
| Error messages | Converts validation and database failures into user feedback. |

### Naive Request Flow

1. A user interacts with a Streamlit widget in `app.py`.
2. `app.py` validates the input.
3. `app.py` runs SQL against SQLite.
4. `app.py` calculates any required analytics.
5. `app.py` renders the result or an error message.

Every workflow crosses several responsibilities inside the same file.

What does this design show?

  • The table assigns six distinct responsibilities to app.py.
  • The request flow sends every user action through the same file.
  • The design provides no boundary between interface behavior and stored task data.
  • Save docs\architecture.md.
  • Count the responsibility rows in the table.

You should see six rows covering routing, widgets, validation, SQL, analytics, and error messages. The single-file proposal now has a visible responsibility map.

Missing part of the responsibility map?

  • Check that the Markdown table begins with the Responsibility column.
  • Check that the final row assigns error messages to app.py.

Ask for help with the document structure: Help me check my TaskTrack responsibility map.

Run the change-impact audit

A responsibility count shows concentration. A change-impact audit reveals how that concentration affects normal development work.

Before you audit the design, how many parts of app.py do you think a new status value will affect?

  • Move to the end of docs\architecture.md.
  • Add the three change scenarios by pasting this content:
## Change-Impact Audit

### Add a New Status Value

- Edit the Streamlit widgets in `app.py` to offer the new value.
- Edit the validation in `app.py` to accept the new value.
- Edit the SQL assumptions in `app.py` to preserve the new value.
- Edit the analytics in `app.py` to group the new value correctly.
- Edit the error messages in `app.py` to describe the allowed values.

Impact: five responsibilities change inside one file.

### Change the Title Validation Rule

- Edit the widget handling in `app.py` to collect valid input.
- Edit the validation in `app.py` to apply the new rule.
- Edit the error messages in `app.py` to explain the new rule.

Impact: the business rule cannot change without editing the UI file.

### Test CRUD Without Streamlit

- Importing `app.py` also imports page routing and widgets.
- CRUD SQL has no repository boundary that tests can call directly.
- Validation, analytics, and error handling arrive through the same import.

Impact: CRUD tests cannot isolate persistence from Streamlit.

What does the audit prove?

  • Adding one status value affects five responsibilities in app.py.
  • Changing one business rule also requires editing the UI file.
  • Testing CRUD imports unrelated Streamlit behavior because the design has no persistence boundary.
  • Save docs\architecture.md.
  • Review the impact statement beneath each scenario.

There it is: routine changes repeatedly reach into the same file. That repeated impact is the intended shortfall in the naive design.

Does the audit look incomplete?

  • Check that the audit contains separate sections for a status change, a validation change, and CRUD testing.
  • Check that every scenario ends with an Impact: statement.

Ask for help tracing the coupling: Help me review my TaskTrack change-impact audit.

Record the architectural shortfall

The audit needs a direct conclusion that later design decisions can answer. Each affected concern should be named separately.

  • Move to the end of docs\architecture.md.
  • Add the audit conclusion by pasting this content:
## Audit Conclusion

The single-file design concentrates unrelated concerns in `app.py`.

- UI changes can affect business rules and persistence code.
- Business rules cannot be tested without importing the UI file.
- Persistence cannot be tested through a dedicated database boundary.
- Analytics cannot evolve without editing the application entrypoint.

UI, business rules, persistence, and analytics cannot be tested or changed independently.

Why state the conclusion directly?

The conclusion turns the audit into a design requirement. The final architecture must give these concerns boundaries that support focused changes and tests.

  • Save docs\architecture.md.
  • Compare the conclusion with the three audit scenarios.

You should see each conclusion supported by evidence above it. Your architecture document now captures both the naive proposal and its observed coupling.

Is the conclusion too vague?

  • Check that the conclusion names UI, business rules, persistence, and analytics.
  • Check that it states these concerns cannot be tested or changed independently.

Ask for help tightening the conclusion: Help me connect my audit evidence to its conclusion.

✔️ Awesome, I've got everything!

Great. Double check that you saved docs\architecture.md with the responsibility map, change-impact audit, and conclusion.

ⓧ I'd like to double check the full code

# TaskTrack Architecture

## Deliberately Naive Single-File Design

The first design places the entire TaskTrack application in `app.py`.

| Responsibility | What `app.py` owns |
| --- | --- |
| Page routing | Selects and displays all five pages. |
| Streamlit widgets | Creates forms, filters, tables, metrics, and charts. |
| Validation | Checks titles, deadlines, priorities, and statuses. |
| SQLite SQL | Opens connections and runs create, read, update, and delete statements. |
| Analytics | Calculates task totals and chart-ready summaries. |
| Error messages | Converts validation and database failures into user feedback. |

### Naive Request Flow

1. A user interacts with a Streamlit widget in `app.py`.
2. `app.py` validates the input.
3. `app.py` runs SQL against SQLite.
4. `app.py` calculates any required analytics.
5. `app.py` renders the result or an error message.

Every workflow crosses several responsibilities inside the same file.

## Change-Impact Audit

### Add a New Status Value

- Edit the Streamlit widgets in `app.py` to offer the new value.
- Edit the validation in `app.py` to accept the new value.
- Edit the SQL assumptions in `app.py` to preserve the new value.
- Edit the analytics in `app.py` to group the new value correctly.
- Edit the error messages in `app.py` to describe the allowed values.

Impact: five responsibilities change inside one file.

### Change the Title Validation Rule

- Edit the widget handling in `app.py` to collect valid input.
- Edit the validation in `app.py` to apply the new rule.
- Edit the error messages in `app.py` to explain the new rule.

Impact: the business rule cannot change without editing the UI file.

### Test CRUD Without Streamlit

- Importing `app.py` also imports page routing and widgets.
- CRUD SQL has no repository boundary that tests can call directly.
- Validation, analytics, and error handling arrive through the same import.

Impact: CRUD tests cannot isolate persistence from Streamlit.

## Audit Conclusion

The single-file design concentrates unrelated concerns in `app.py`.

- UI changes can affect business rules and persistence code.
- Business rules cannot be tested without importing the UI file.
- Persistence cannot be tested through a dedicated database boundary.
- Analytics cannot evolve without editing the application entrypoint.

UI, business rules, persistence, and analytics cannot be tested or changed independently.

Before the final check, which parts of the document do you expect to prove that app.py is carrying too many responsibilities?

  • Return to docs\architecture.md in the confirmed code editor.
  • Trace the status-change scenario through its listed responsibilities.
  • Trace the CRUD-testing scenario to its Streamlit import problem.
  • Read the final audit conclusion.

You should see at least five responsibilities affected by the status change. You should also see a direct conclusion that UI, business rules, persistence, and analytics cannot be tested or changed independently.

You have exposed the cost of concentrating TaskTrack in one file. Next, you will use this evidence to give each responsibility a clear architectural home.

Design the Layered Architecture

Your single-file audit proved that changes to TaskTrack would spread across one file. That coupling blocks independent testing.

A layered architecture gives each responsibility one clear home. This structure applies separation of concerns before implementation begins.

In this step, get ready to:
  • Define the final module map for TaskTrack.
  • Trace requests through the application layers.
  • Specify the SQLite tasks schema.
Map each module to one responsibility

A module map turns the audit findings into boundaries. Each module should have one main reason to change.

What belongs in the module map?

  • The app.py file is the entrypoint. It declares pages with st.Page. It routes between them with st.navigation.
  • The views directory contains five view modules. Each module matches one page already named in docs\requirements.md. The views\add_task.py module handles the Create Task interface.
  • The models\task.py module defines the cohesive Task data record.
  • The database directory contains a connection module. The database\task_repository.py module owns task storage operations.
  • The services\task_service.py module coordinates task use cases. It invokes validation before persistence. A separate analytics service prepares summary data.
  • The utils directory contains validators. It also contains small reusable helpers.
  • The project includes a tests directory. It also includes .streamlit\config.toml. The remaining root files are requirements.txt and README.md.
  • Switch back to the docs\architecture.md tab in your confirmed code editor.
  • Append a Final Layered Architecture section beneath the existing audit using the module responsibilities above.
  • Save docs\architecture.md.

You should now see the naive audit followed by a final module map. The map should place routing in the entrypoint without placing validation or SQL there.

Trace requests through the layers

A request flow shows how the boundaries cooperate. The repository boundary keeps persistence details away from the interface.

How does work move?

  • The app.py router selects a view in Streamlit.
  • The views\add_task.py view collects Create Task input. It passes that input to services\task_service.py.
  • The task service validates input. It coordinates the requested operation. It calls database\task_repository.py after validation succeeds.
  • The task repository uses parameterized sqlite3 operations. Those operations read from the tasks table or write to it.
  • The analytics service converts repository results into pandas DataFrame objects. Streamlit renders metrics from that data. It renders charts with st.bar_chart.

Why st.navigation instead of pages?

The st.navigation approach makes app.py an explicit router. It also gives the five views shared entrypoint behavior.

The simpler pages/ mechanism provides less control over this routing plan. Explicit routing makes the application flow easier to review.

  • Add a Request and Data Flows section to docs\architecture.md using the flows above.
  • Save docs\architecture.md.
  • Trace the Create Task flow from the view to the storage table.

You should be able to follow views\add_task.py to services\task_service.py. The next boundary should be database\task_repository.py before the flow reaches the tasks table.

Specify the tasks table contract

The database schema is a contract between the task service and the repository. Clear field rules prevent later implementation guesses.

What does the tasks table store?

  • The id column uses INTEGER PRIMARY KEY.
  • The title column is required. The service rejects a title that is empty after trimming.
  • The description column is optional. It stores text when the learner supplies a description.
  • The deadline column is optional. It stores an ISO-formatted date as TEXT.
  • The priority column allows Low. It also allows Medium or High. A CHECK constraint protects those values. Its default is Medium.
  • The status column allows To Do. It also allows In Progress or Done. A CHECK constraint protects those values. Its default is To Do.
  • The created_at column stores a UTC text timestamp. The updated_at column stores the latest UTC update timestamp.
  • Add a Tasks Table Specification section to docs\architecture.md using the field contract above.
  • Save docs\architecture.md.

You should now see one field definition for every value required by the TaskTrack workflows. The allowed priority values should match docs\requirements.md exactly.

Why does updated_at need an update rule?

A column default applies when the repository inserts a row. It does not refresh itself during a later update.

Every repository update must set updated_at to a new UTC text timestamp. That rule keeps the stored modification time trustworthy.

✔️ Awesome, I've got everything

Your final architecture now follows the coupling audit in docs\architecture.md. Save the document before completing the final trace.

ⓧ I'd like to double check the full design

Compare your architecture document with this final checklist.

  • The naive single-file audit remains at the start of the document.
  • The final module map includes the entrypoint. It includes five view modules. It also includes the model layer.
  • The module map includes database connection responsibilities. It includes repository responsibilities.
  • The module map includes task services. It includes analytics services. It also includes validators and helpers.
  • The supporting structure includes tests. It includes .streamlit\config.toml. It also includes requirements.txt and README.md.
  • The Create Task flow passes through the view. It continues through the task service. It reaches the task repository before storage.
  • The analytics flow turns repository results into pandas DataFrame objects. Streamlit uses those objects for metrics and bar charts.
  • The tasks table defines its primary key. It also defines required fields and optional fields.
  • The table constrains priority values. It also constrains status values.
  • The timestamp plan stores UTC text values. It requires updates to refresh updated_at explicitly.

Before you trace the finished design, which boundary do you expect to own validation?

  • Start at views\add_task.py in the Create Task flow.
  • Follow the flow until it reaches the tasks table.
  • Check the table specification against the field rules in docs\requirements.md.

You should trace Create Task through views\add_task.py. The path should continue through services\task_service.py and database\task_repository.py before reaching the tasks table.

That complete trace proves that the interface no longer owns validation or persistence.

Can't trace the flow cleanly?

  • Check that the view calls the task service without calling the repository directly.
  • Check that the task service performs validation before requesting persistence.
  • Check that only the task repository communicates with the tasks table.

Ask for help with the boundaries if the responsibilities still overlap: Help me review my TaskTrack layer boundaries.

Your architecture now gives each TaskTrack responsibility a clear boundary. Next, you'll turn those boundaries into a test strategy and an ordered delivery plan.

Plan Testing and Delivery

Your requirements now define the product. Your layered architecture gives every responsibility a clear home.

Architecture becomes implementation-ready when tests can prove each boundary. The remaining work also needs a dependency order that keeps each stage reviewable.

In this step, get ready to:
  • Define the testing strategy for every architecture boundary.
  • Document the remaining delivery path.
  • Commit the complete design pack to Git.
Define the test strategy

A layered design pays off when each boundary can be tested on its own. The testing strategy uses pytest to separate focused checks from tests that cross into SQLite.

  • Return to docs/test-plan.md in the editor from earlier.
  • Replace the empty document with this test plan:
# TaskTrack Test Plan

## Validator Unit Tests

- Verify that title validation trims input and rejects an empty result.
- Verify that optional fields remain optional.
- Verify that priority accepts Low, Medium, or High.
- Verify that status accepts To Do, In Progress, or Done.

## Repository CRUD Tests

- Give every repository test a unique SQLite database inside pytest's tmp_path directory.
- Cover create, read, update, and delete operations.
- Confirm schema constraints reject invalid stored values.
- Confirm update operations refresh updated_at.

## Service Tests

- Test business rules without importing Streamlit views.
- Confirm services call validators before repository operations.
- Confirm services coordinate repository results for each workflow.

## Integration Tests

- Connect the real service layer to the real repository layer.
- Use a unique tmp_path SQLite database for each integration test.
- Cover workflows that cross service and repository boundaries.

How Does This Plan Divide Coverage?

  • Validator unit tests prove that field rules work without loading the application.
  • Repository CRUD tests exercise storage through a unique tmp_path database for every test.
  • Service tests prove business rules without depending on the interface.
  • Integration tests prove that real service calls reach the repository correctly.
  • Save docs/test-plan.md.
  • Scan the saved headings to confirm all four test levels are present.

You should see separate sections for validators, repository CRUD, services, and integration coverage. The repository sections should use a unique temporary database for each test.

Does the Test Plan Feel Incomplete?

Check that every layer from the architecture has a matching test level. Make sure the repository section includes create, read, update, and delete operations.

Confirm that both repository and integration tests use a unique tmp_path database.

Help me compare my TaskTrack test plan with the layered architecture.

✔️ Awesome, I've got everything!

Your test plan now gives every architecture boundary a focused proof strategy.

ⓧ I'd like to double check the full code

# TaskTrack Test Plan

## Validator Unit Tests

- Verify that title validation trims input and rejects an empty result.
- Verify that optional fields remain optional.
- Verify that priority accepts Low, Medium, or High.
- Verify that status accepts To Do, In Progress, or Done.

## Repository CRUD Tests

- Give every repository test a unique SQLite database inside pytest's tmp_path directory.
- Cover create, read, update, and delete operations.
- Confirm schema constraints reject invalid stored values.
- Confirm update operations refresh updated_at.

## Service Tests

- Test business rules without importing Streamlit views.
- Confirm services call validators before repository operations.
- Confirm services coordinate repository results for each workflow.

## Integration Tests

- Connect the real service layer to the real repository layer.
- Use a unique tmp_path SQLite database for each integration test.
- Cover workflows that cross service and repository boundaries.

What Should the Full File Contain?

This reference contains the complete test strategy. Its four sections match the validator, repository, service, and integration boundaries from the architecture.

Document the delivery path

The backlog should build foundations before user-facing workflows. This order keeps each stage small enough to implement without reopening earlier architecture decisions.

The README.md gives reviewers a shorter route through the complete design pack. It connects the product purpose to the planned implementation.

  • Return to docs/implementation-plan.md in the editor from earlier.
  • Replace the empty document with this delivery plan:
# TaskTrack Implementation Plan

The remaining work follows dependency order so every stage builds on a reviewed foundation.

## Delivery Order

1. **Scaffold:** Create the planned application structure and project configuration.
2. **Database:** Build the SQLite connection and tasks repository.
3. **Models and services:** Add the Task model, validators, task service, and analytics service.
4. **Create flow:** Connect the Add Task view to validation and persistence.
5. **List and search:** Display tasks with search, filtering, and sorting.
6. **Manage flow:** Add task updates and deletion.
7. **Dashboard and analytics:** Render statistics, metrics, and charts.
8. **Testing and polish:** Complete automated coverage and refine error handling.
9. **README and publication:** Update usage guidance and publish the finished project.

Why This Order?

  • The scaffold establishes the planned file structure.
  • The database provides storage before user workflows depend on it.
  • Models plus services establish the business boundary before views call it.
  • Testing plus polish comes before the final publication pass.
  • Save docs/implementation-plan.md.
  • Read the numbered stages from top to bottom to confirm each stage depends only on earlier work.

You should see nine stages beginning with the scaffold. The final stage should cover the README plus publication.

Does the Backlog Jump Ahead?

Check that database work appears before any create or manage workflow. Confirm that models plus services appear before views depend on their rules.

Help me review the TaskTrack delivery order.

✔️ Awesome, I've got everything!

Your implementation backlog now moves from foundations to publication in dependency order.

ⓧ I'd like to double check the full code

# TaskTrack Implementation Plan

The remaining work follows dependency order so every stage builds on a reviewed foundation.

## Delivery Order

1. **Scaffold:** Create the planned application structure and project configuration.
2. **Database:** Build the SQLite connection and tasks repository.
3. **Models and services:** Add the Task model, validators, task service, and analytics service.
4. **Create flow:** Connect the Add Task view to validation and persistence.
5. **List and search:** Display tasks with search, filtering, and sorting.
6. **Manage flow:** Add task updates and deletion.
7. **Dashboard and analytics:** Render statistics, metrics, and charts.
8. **Testing and polish:** Complete automated coverage and refine error handling.
9. **README and publication:** Update usage guidance and publish the finished project.

What Should the Full File Contain?

This reference preserves the complete implementation sequence. Every workflow appears after the layers it needs.

  • Return to the empty README.md at the TaskTrack repository root.
  • Add this summary of the complete Stage 1 design pack:
# TaskTrack

TaskTrack is a local task manager for individuals who need a private, simple way to organize and track their work without cloud services.

## Product Experience

The five-page experience supports task creation, viewing, search, filtering, sorting, management, and analytics.

## Architecture

app.py routes pages to thin view modules. Views call services for validation and workflow coordination. Services call repository modules for parameterized SQLite operations. Models define task data. Utility modules hold validators and helpers. The analytics service prepares pandas DataFrame objects for Streamlit metrics and charts.

## Data and Validation

SQLite stores tasks with constrained priority and status values. Validation trims required titles before storage. Optional descriptions and deadlines remain nullable. Repository updates refresh updated_at explicitly.

## Testing Strategy

Validator unit tests cover field rules. Repository CRUD tests use a unique pytest tmp_path database. Service tests cover business rules. Integration tests cross service and repository boundaries.

## Delivery Roadmap

Implementation proceeds through the scaffold, database, models and services, create flow, list and search, manage flow, dashboard and analytics, testing and polish, then README and publication.

What Does This Summary Capture?

  • The opening defines TaskTrack as a private local task manager.
  • The product section summarizes the five-page experience through observable workflows.
  • The architecture plus data sections explain responsibility boundaries and storage rules.
  • The final sections summarize proof through tests plus staged delivery.
  • Save README.md.
  • Scan every section to confirm the summary covers purpose, experience, architecture, storage, validation, testing, and delivery.

You should now have a short project overview that points reviewers toward the decisions documented across the design pack.

Is the README Missing a Design Decision?

Compare the README headings with the target design pack. Confirm that the summary covers both how TaskTrack is structured and how the implementation will be tested.

Help me check my TaskTrack README summary.

✔️ Awesome, I've got everything!

Your README now gives reviewers a concise map of the complete architecture package.

ⓧ I'd like to double check the full code

# TaskTrack

TaskTrack is a local task manager for individuals who need a private, simple way to organize and track their work without cloud services.

## Product Experience

The five-page experience supports task creation, viewing, search, filtering, sorting, management, and analytics.

## Architecture

app.py routes pages to thin view modules. Views call services for validation and workflow coordination. Services call repository modules for parameterized SQLite operations. Models define task data. Utility modules hold validators and helpers. The analytics service prepares pandas DataFrame objects for Streamlit metrics and charts.

## Data and Validation

SQLite stores tasks with constrained priority and status values. Validation trims required titles before storage. Optional descriptions and deadlines remain nullable. Repository updates refresh updated_at explicitly.

## Testing Strategy

Validator unit tests cover field rules. Repository CRUD tests use a unique pytest tmp_path database. Service tests cover business rules. Integration tests cross service and repository boundaries.

## Delivery Roadmap

Implementation proceeds through the scaffold, database, models and services, create flow, list and search, manage flow, dashboard and analytics, testing and polish, then README and publication.

What Should the Full File Contain?

This reference is the complete README summary. Its sections connect TaskTrack's purpose to architecture, testing, and delivery.

Commit the design pack

A commit creates a review point for the complete Stage 1 blueprint. It preserves the requirements plus every architecture decision before implementation begins.

  • Switch back to the PowerShell terminal at the TaskTrack repository root.
  • Review the design pack changes by running:
git status

What Does This Command Check?

The command inspects the repository before anything is staged. It shows which paths belong to the new design pack.

You should see README.md plus the docs directory listed as untracked content.

  • Stage the complete design pack by running:
git add .

What Does Staging Do?

Staging selects the current TaskTrack content for the next commit. This includes the requirements plus every completed design document.

  • Confirm the design pack is staged by running:
git status

What Changed in the Status?

The second status check should place every design file in the staged group. That confirms the next commit includes the full package.

Git uses your configured commit editor to collect the message. Enter the exact message Plan TaskTrack architecture when that editor opens.

  • Create the architecture commit by running:
git commit

What Does This Command Record?

The command records the staged design pack as one repository snapshot. Its message identifies the purpose of the Stage 1 commit.

  • Enter Plan TaskTrack architecture as the commit message.
  • Save the commit message in your configured editor.
  • Close the commit editor to finish the commit.

You should see a commit summary in PowerShell after the editor closes. The summary confirms that the staged files were recorded.

Did the Commit Stop?

If Git asks for author details, follow the configuration guidance shown in PowerShell. Rerun the commit after the identity is configured.

If no files are included, rerun the staging command from the TaskTrack repository root.

Help me finish my TaskTrack architecture commit.

Before you inspect the history, what commit message do you expect to see at the top?

  • Inspect the three newest commits by running:
git log -3

What Does This History Check Prove?

The command displays up to three recent commits. The newest entry proves that the complete Stage 1 design pack has a saved review point.

You should see Plan TaskTrack architecture as the newest commit message. That confirms the requirements, architecture, test strategy, backlog, and README are committed together.

That's the planning sprint complete. TaskTrack now has an implementation-ready blueprint with a committed test strategy plus delivery order.

Secret mission

Add a Failure-Mode Matrix

Your design pack explains how TaskTrack succeeds. Add a failure-mode matrix that maps six realistic errors to detection, safe feedback, rollback, and tests before Stage 2 begins.

Clean Up Your Resources

Clean Up Your Resources

Your Stage 1 work lives entirely in local files, so there are no cloud resources or ongoing costs. Choose whether to keep the design pack available, close it for now, or delete it entirely.

Resources you used:

  • The TaskTrack project folder containing the local Git repository, commit history, README.md file, and four design documents under docs.

Keep everything running

No action needed. Choose this if you want to continue from the committed architecture package.

  • Keep the TaskTrack folder in its current location.
  • Keep the repository open in your confirmed code editor.
  • Use the existing commit history as your checkpoint before starting the scaffold stage.

Pause - I'll come back to this later

Close the current editor session while keeping every local file and commit. Stage 1 created documentation only, so there are no application processes to stop.

  • Close the TaskTrack workspace in your confirmed code editor.
  • Leave the TaskTrack folder in its current location.
  • Reopen the same folder when you are ready to begin the scaffold stage.

Delete - I don't want to use this again

Permanent deletion removes the design documents and both local commits. Your work has no cloud copy, so continue only if you no longer need the TaskTrack blueprint.

  • Close your confirmed code editor.
  • Press the Windows key to open Windows search.
  • Type File Explorer and press Enter to open it.
  • Return to the location where you created the TaskTrack folder.
  • Select the TaskTrack folder.
  • Press Shift+Delete to request permanent deletion.
  • Confirm the deletion in the Windows prompt.

You should no longer see the TaskTrack folder in its previous location. This confirms that the design pack and local repository have been removed.

Nice Work!

Nice Work!

You did it! You produced a complete Stage 1 design pack that turns TaskTrack into an implementation-ready project.

Your local repository now gives reviewers a clear path from user needs to architecture decisions.

What you learned:

  • Translated TaskTrack's five-page product brief into testable acceptance criteria for every requested workflow.
  • Used a single-file responsibility audit to expose how concentrating every responsibility in app.py blocks independent testing.
  • Designed a layered architecture that traces each request from a Streamlit view through service boundaries to a repository. Defined SQLite schema constraints for implementation. Sequenced pytest coverage through an incremental delivery plan.
  • Secret Mission: Added a committed failure-mode matrix for realistic application failures. Each row identifies the detecting layer. Each row defines a safe response. Each row records the rollback decision. Each row names the required pytest coverage.

Ready to quiz yourself?