Backend Architecture Case Study

Ursa Note

A DB-first knowledge workspace designed to allow information to start messy and become structured over time without losing identity, ownership, or storage reliability.

Problem Context

People rarely capture knowledge in structured formats. Instead, ideas are stored as fragments such as rough thoughts, screenshots, and incomplete notes.

  • Identity drift when notes are renamed or moved
  • Maintaining consistency between database metadata and file storage
  • Premature AI classification locking users into incorrect structures
  • Difficulty managing long-lived knowledge systems

Challenge: Design a backend system that allows knowledge to evolve while preserving structural integrity and predictable behaviour.

Design Philosophy

  • Database must be the source of truth
  • Identity should be independent of storage location
  • State changes must be explicit and auditable
  • AI should assist understanding, not enforce structure

Architecture

Data Flow

  • User action triggers API request
  • Backend validates request and permissions
  • Database state is updated
  • Storage objects are synchronized
  • Response is returned to client

System Layers

  • FastAPI application logic layer
  • PostgreSQL relational state layer
  • MinIO S3-compatible object storage layer

Storage Model

  • UUID-based identity
  • Deterministic storage paths derived from metadata
  • Real exportable Markdown files

Engineering Decisions

Use PostgreSQL as source of truth

Reason: Guarantee relational consistency, ownership tracking, and predictable state behaviour

Tradeoff: Reduced flexibility compared to NoSQL document databases

Alternative: MongoDB and document storage models were rejected due to relationship integrity risks

Managed workspace model instead of open filesystem editing

Reason: Prevent synchronization drift, race conditions, and ambiguous storage state

Tradeoff: Users cannot directly modify storage structure

Alternative: Open vault-style storage models were avoided to maintain deterministic behaviour

Inbox-first workspace invariant

Reason: Ensure notes always have a valid starting ownership state

Tradeoff: Reduced initial customization flexibility

Failure Handling

  • Database write succeeds but storage upload fails

    → Transactional-style operation sequencing and rollback logic

  • Concurrent note updates

    → Backend-enforced ownership and validation checks

  • Storage path collisions

    → UUID-derived deterministic storage keys

Performance Strategy

  • Prioritise synchronous MVP operations for consistency
  • Design async pipelines for future AI processing
  • Use storage abstraction to enable cloud migration

AI Strategy

AI is treated as an interpretation and enrichment layer rather than a structural controller.

  • Background knowledge enrichment processing
  • Topic clustering across notes
  • Temporal knowledge evolution analysis

Impact

Technical

Demonstrates deterministic backend design for long-lived knowledge systems

Product

Allows users to capture ideas without worrying about early organisation

Learning

Improved system design thinking, constraint modeling, and production architecture awareness

Reflection

The hardest part of building UrsaNote was deciding what the system must guarantee — and what it must explicitly refuse to allow.