studysprint/notes/architecture-note.md

Study Sprint - Architecture Redesign Notes

Purpose of this note

This note documents the architectural and UI redesign work completed on the app documenting

• what changed
• why it changed
• how the strucutre improved
• which design decisions were intentional

---

Initial app state

The app originally had a flatter and more fragmented structure than the actual data model supported.

The conceptual data hierarchy of the app is:

Subject -> Assignment -> Task

However, the earlier navigation and screen structure did not consistently reflect that hierarchy. In practice, this caused duplicated views, weak context, and screens that felt disconnected from their parent entities.

Main problems in the earlier version:

• top-level tabs included separate screens for Subjects, Assignments, and Tasks
• tasks existed as their own top-level area even though they are children of assignments
• assignments also felt partially detached from subjects
• repeated CRUD patterns created too many screens and too much UI duplication
• many screens relied on older defaultStyles patterns rather than a clearer component/card-based structure
• raw timestamps and brrittle date inputs created poor usability
• create/edit flows were separated even when both used the same form structure

---

Core redesign goal

The redesign aimed to make the app follow its real conceptual model more closely

Dashboard -> overview Subjects -> actual content hierarchy entry point Timer -> separate utility tool

And inside the content structure:

Subject -> Assignment -> Task

The main design philosophy throughout the redesign was:

• calm
• intuitive
• minimal
• low visual noise
• predictable interaction patterns
• stronger hierarchy
• less redundancy

---

1. Navigation architecture redesign

Previous navigation problem

The earlier tab setup exposed too many top-level destinations:

• Dashboard/Home
• Subjects
• Assignments
• Tasks
• Timer

THis was a problem because Tasks and Assignments were not truly top-level concepts in the product model. They belong to parent entities.

This caused:

• duplicated list views
• extra screens with weaker contextual meaning
• cognitive overload
• a flatter app structure than intended

Navigation redesign decision

The top-level tabs were simplified to:

• Dashboard
• Subjects
• Timer

Why this is better

This better matches the app structure:

• Dashboard = overview and corss-cutting information
• Subjects = main entry point into academic content
• Timer = standalone utility

Assignments and tasks were removed from the top-level tab bar and are now only accessed through the hierarchy:

• subject details contains assignments
• assignment details contain tasks

Effect of this change

This reduced redundancy and made the app feel more coherent. It also aligned the user flow with the actual data relationships rather than exposing every model as its own first-class navigation area.

---

2. Content hierarchy redesign

Original issue

Subjects, assignments, and tasks were partially treated like parallel entities rather than nested entities.

This weakened context:

• a task could appear without clearly indicating its assignment or subject
• an assignment could feel detached from its subject
• the hierarchy existed in the database but was not always communicated in the UI

Redesign decision

The hierarchy was made explicit in the UI

• subjects page shows only subject cards
• subject detail page becomes the main hub fro the selected subject
• assignment detail page becomes the main hub for the selected assignment
• task detail page becomes the main hub for the selected task

Result

The app now better communicates:

• where the user is
• what the current item belongs to
• how to move deeper into the structure

---

3. Subject list redesign

Original issue

The subject list screen contained too much management UI directly in the list:

• edit buttons
• delete buttons
• progress bar
• cluttered card actions

This made the subject list feel like a control panel rather than a clean browsing screen.

Redesign decision

The subject list was simplified into clean, tappable subject cards.

Each subject card now focuses on:

• subject title
• optional description
• active/inactive pill
• subject-specific color identity
• full-card tap to open subject details

Removed from list cards

• inline edit button
• inline delete button
• progress bar
• management-heavy layout

Why

The list screen should be for browsing and selecting. Management actions belong inside the detail screen for that entitiy

Result

The subject list become calmer, easier to scan, and more aligned with the principle that cards should act as entry points rather than mini dashboards.

---

4. Subject detail screen redesign

Original issue

The subject detail screenw as still using older styling patterns and did not fully behave as the subject "hub".

Redesign decision

The subject detail screen was redesigned as the main management hub for the specific subject.

It now includes:

• a subject summary card
• subject status and metadata
• subject-specific color styling
• subject actions (edit/delete)
• create assignment action
• assignment sections below the subject summary

Why this matters

This screen now clearly answers:

• what this subject is
• how active/complete it is
• what assignments belong to it
• what actions can be taken at the subject level

This better reflects the product structure.

---

5. Assignment detail screen redesign

Original issue

Assignments were previously styled more generically and did not always preserve clear subject context.

Redesign decision

The assignment detail screen was redesigned to:

• function as the hub for one assignment
• show clear metadata
• show progress through child tasks
• expose only assignment-relevant actions
• preserve visual inheritance from the parent subject

New structure

The assignment detail screen now includes:

• assignment summary card
• subject context pill
• deadline metadata
• progress section showing task completion
• task list organized by completion state
• create task action

Why

Assignments are not independent from subjects. The redesign makes that relationship visible without making the screen visually noisy.

---

6. Task detail screen redesign

Original issue

Tasks were at risk of losing hierarchical context because they are the deepest level in the model.

Redesign decision

The task detail screen was redesigned to preserve parent context explicitly.

It now includes:

• task summary card
• subject context pill
• assignment context pill
• task state and metadata
• parent-aware styling

Why

Tasks are the easiest place for context loss. By surfacing both subject and assignment, the user always knows where the task belongs.

---

7. Upsert-based form architecture

Original issue

The app originally used separate create and edit screens for the same entities, even when both screens used almost identical form fields and validation.

This created:

• duplicated UI code
• repeated logic
• more route clutter
• higher maintenance cost

Redesign decision

Create/edit flows were consolidated into upsert-style screens where appropriate.

Implemented

• upsertSubject
• upsertAssignment
• upsertTask

Pattern used

The form checks whether an ID exists:

• if no ID exists -> create mode
• if an ID exists -> edit mode

The same screen handles:

• initial default values
• loading existing data when editing
• submit behavior for insert vs update

Why this is better

This reduces duplication while keeping the form styling and validation consistent.

Tradeoff

This introduces a little more branching inside a single screen, but the tradeoff is worth it because create and edit flows are structurally very similar for these entities.

---

8. Shared utility extraction

Original issue

Small but important logic was duplicated across screens.

Redesign decision

Shared helpers were moved into reusable modules.

Added shared utilities

• lib/date.ts
• lib/subjectColors.ts

Date formatting utility

A shared date formatting module was introduced to standardize:

• date-only display
• date-time display

This replaced raw timestamp rendering such as ISO strings.

Why

Raw database timestamps were ugly and difficult to read. Formatting them centrally improves both UI quality and consistency.

Subject color utility

A shared subject color configuration was introduced to centralize:

• available subject colors
• subject color type
• mapping from logical color key to visual values
• helper function for retrieving the correct color set

Why

This prevents duplicated color logic and ensures consistent us of subject-specific accent colors across screens.

---

9. Subject color system and inheritance

Original issue

The app initially relied mainly on global app accent colors, which made it harder to preserve identity across nested subject content.

Redesign decision

Subjects were given their own user-selectable accent color.

Color choice

The user chooses from a controlled palette instead of arbitrary colors.

Why a controlled palette

This preserves:

• aesthetic consistency
• readability
• predictable contrast
• low visual noise

How color is used

The subject color is used as a contextual accent, not a replacement for the whole theme.

Used on:

• subject card border
• subject preview card
• subject pills
• inherited borders and indicators in assignment/task screens
• progress bars and completion indicators where appropriate

Important design rule

The subject color was not used for everything.

Primary action buttons such as:

• create
• save
• login remain on the global app accent

Why

This preserves a consistent interaction language:

• app accent = primary action
• subject color = content identity / context

This separation was an intentional design decision.

---

10. Card-based UI redesign

Original issue

Several screens still relied on older layout/styling conventions that felt less coherent and more cluttered.

Redesign decision

The redesign shifted toward a more consistent card-based interface using:

• bordered surface cards
• semantic Tailwind theme classes
• more restrained spacing
• contextual pills
• reduced action clutter

Card design goals

• easier scanning
• stronger visual hierarchy
• fewer floating controls
• more predictable composition

Result

The app feels more structured and less noisy.

---

11. Metadata and pill system

Original issue

Status and metadata were previously shown in less consistent ways, including redundant indicators.

Redesign decision

Metadata display was standardized using pill elements for small contextual information.

Examples include:

• subject name
• assignment parent
• deadline
• active/inactive state

Important cleanup decision

Some pills were removed when they became redundant.

Example:

• completed/in-progress pill was removed in places where the same information was already communicated by a checkbox or progress structure

Why

This reduced duplication and visual clutter.

---

12. Progress display redesign

Original issue

Progress indicators were previously placed too aggressively in list views where they created clutter.

Redesign decision

Progress bars were kept only where they make structural sense:

• subject detail
• assignment detail

Why

These are hub screens where progress is meaningful.

Progress bars were intentionally removed from places like subject list cards where they overloaded a browsing view.

Additional improvement

Progress is now shown with both:

• a percentage bar
• an x / y completed count
• remaining item count text

This makes progress more understandable than a bar alone.

---

13. Authentication-related debugging insight

During development, a major debugging issue turned out not to be screen architecture at all, but session/auth failure.

This surfaced as:

• fetch failures
• apparent data loading errors
• misleading “network request failed” behavior

Takeaway

Auth state and session expiry can easily masquerade as architecture or fetch bugs.

This reinforced the importance of:

• clearer auth handling
• not assuming every fetch failure is a UI/data issue
• checking session state early when debugging

---

14. Time handling and dual-boot issue insight

A separate development issue was discovered related to system time mismatch in a Windows/Linux dual-boot environment.

Although not an app architecture feature directly, it affected development by causing:

• failed requests
• misleading network/auth behavior

Development takeaway

System time correctness matters for:

• authentication
• HTTPS
• tokens
• scheduled features

This was important context during debugging and implementation.

---

15. Notifications and reminders

Assignment creation/updating included work around deadline reminders.

Behavior

When an assignment has a valid future deadline:

• a reminder can be scheduled
• previous reminders are updated/cancelled when necessary
• notification IDs are stored through async storage helpers

Why this matters architecturally

This means assignment upsert behavior is not only CRUD. It also coordinates:

• persistence
• reminder scheduling
• reminder cleanup

This is relevant for the final report because it shows that form flows have side effects beyond database writes.

---

16. General design principles used across the redesign

Principle 1: reflect the true data hierarchy

The UI should match the conceptual model:

• subjects contain assignments
• assignments contain tasks

Principle 2: remove redundant top-level structure

Not every data model deserves a top-level tab.

Principle 3: keep list screens for browsing

Heavy management actions should live in detail screens.

Principle 4: preserve context

The deeper the user goes, the more important parent context becomes.

Principle 5: use color as identity, not decoration

Subject colors provide contextual identity without overwhelming the UI.

Principle 6: keep primary actions globally consistent

App accent remains the primary action language.

Principle 7: reduce duplication

Reusable upsert screens and shared utilities reduce maintenance cost.

Principle 8: avoid visual noise

Redundant pills, repeated indicators, and crowded cards were intentionally reduced.

---

17. Current architecture summary

Tabs

• Dashboard
• Subjects
• Timer

Hierarchy

• Subject
  • Assignment
    • Task

Reusable utilities

• date formatting
• subject color mapping
• progress checks
• async storage notification helpers

Form strategy

• upsert-style forms for core entities

Design system

• NativeWind
• semantic Tailwind tokens
• shared card/pill patterns
• subject color inheritance

---

18. Final outcome

The redesign changed the app from a flatter CRUD-style structure into a more coherent hierarchical study workflow.

The main improvements were:

• better navigation structure
• reduced redundancy
• clearer subject/assignment/task relationships
• stronger contextual design
• less cluttered list screens
• reusable form patterns
• centralized shared helpers
• more polished and consistent UI

Overall, the app now better reflects its intended purpose as a study productivity tool organized around the academic structure of: Subject → Assignment → Task

---

19. Possible items to mention later in the final report

These are likely worth discussing explicitly:

• why Tasks and Assignments were removed as top-level tabs
• why subject detail and assignment detail were turned into hubs
• why create/edit were merged into upsert patterns
• why a controlled color palette was used instead of arbitrary colors
• why subject color was used for context, not for primary actions
• why duplicated metadata indicators were removed
• why shared date formatting and subject color utilities were extracted
• how preserving hierarchy improved usability
• how debugging/auth issues affected development decisions