Backend Domain Models

PRKS organizes research data through a set of structured backend domain models. These models define the lifecycle and relationships for research entities such as Works, PDF annotations, and the Research Network. The system currently uses SQLite for persistence but maintains architecture boundaries to support a planned transition to PostgreSQL and multi-user environments.

Sources: README.md:3-8, AGENTS.md:3-10, backend/AGENTS.md:5-10

Identity and Authorization Models

The identity system governs access control and request processing. It distinguishes between authentication (verifying who a user is) and authorization (verifying what a user can do).

RequestContext

The RequestContext model encapsulates the state of an active request. Constructors for sessions, background jobs, and administrative tasks build this context. It does not store user roles directly to ensure that authorization checks always consult the latest membership data during a transaction.

Sources: AGENTS.md:120-125, backend/domain/identity/authorization.py

Authorization Logic

The authorize() function validates capabilities against a role-to-capability table. It reads the current membership within the scope of a protected database transaction.

The diagram above shows the flow of authorization validation during a backend request.
Sources: AGENTS.md:120-130, backend/domain/identity/authorization.py

Work Identity Model

The Work model identifies unique research items. In the current schema (version 17), the works table serves as the primary authority for all metadata. Other structures like manifestations and assets exist as trigger-maintained projections of the works table.

Sources: backend/AGENTS.md:215-225, README.md:155-160

Research Network Models

The Research Network represents structured relationships between research entities. These models allow users to map arguments and evidence across different source materials.

• Concepts: Unique ideas or subjects identified across multiple works.
• Positions: Theoretical stances or viewpoints related to specific research areas.
• Arguments/Stances: Explicit claims supported or opposed by research notes.

Research Graph

The Research Graph is a read-only projection of the Research Network. It connects Concepts, Positions, and Arguments through note references.

The diagram above illustrates the relationships between core entities in the Research Network.
Sources: README.md:11-15, README.md:162-165, backend/AGENTS.md:38-42

PDF and Annotation Models

PRKS manages PDF files and their associated metadata as distinct domain entities.

Managed PDFs

The system treats PDF bytes as private research material. Metadata such as the file path (works.file_path) links a Work to its physical file. The backend ensures path containment using safe_pdf_path_under_dir() to prevent directory traversal.

PDF Annotations

Canonical annotation metadata is stored in the database. This data is separate from the PDF bytes and is synchronized through a durable acknowledgement protocol.

Sources: backend/AGENTS.md:105-110, AGENTS.md:138-140, README.md:15-20

Durable Cleanup and Recovery

The backend implements specific models for post-commit cleanup to ensure consistency between the database and the filesystem.

PDF Cleanup Lifecycle

When a Work is deleted, the system records the filename in a pending_pdf_cleanup table. This occurs inside the same transaction as the Work deletion. A background process later settle these claims by verifying no other Work references the file before unlinking the bytes.

This sequence ensures that managed PDF bytes are not orphaned if a process crashes between a database commit and a filesystem operation.
Sources: backend/AGENTS.md:130-165

Data Classification

Domain components are classified by their durability requirements for backup and restore operations.

Sources: backend/AGENTS.md:75-85

Backend domain models provide the foundation for the PRKS research environment. By separating canonical authority from derived projections and operational state, the system maintains data integrity while preparing for future scalability milestones.