Skip to content

Document current-state architecture, data flows, and security boundaries #26

Description

@DenWin

Parent: #24. Blocked by the reviewed behavior/testability audit in #17.

Goal

Create docs/architecture.md as a verified current-state description. Keep target architecture and refactoring proposals clearly separated.

Required content

  • Context, goals, constraints, and supported runtime/deployment model.
  • System context and container/module diagrams.
  • Application bootstrap and request-routing flow.
  • Authentication/session flow, including JWT secret lifecycle and anonymous modes.
  • Job lifecycle from page load through upload, conversion, progress, results, download, deletion, and scheduled cleanup.
  • SQLite schema, relationships, migrations, WAL, and persistence assumptions.
  • Filesystem layout, ownership, path-containment boundaries, and data volume.
  • Converter catalog, selection priority, process execution, concurrency, status propagation, and failure behavior.
  • Browser/server responsibilities.
  • Configuration sources and precedence.
  • External dependencies and trust boundaries.
  • Current test seams and known testability limitations.
  • Current versus target architecture markers.

Diagrams

At minimum:

  • system context
  • container/module relationships
  • authenticated conversion sequence
  • job state/data flow
  • deployment and persistent-volume view
  • trust/security boundaries

Diagrams must have text explanations and remain reviewable in source control.

Acceptance criteria

  • Every diagram matches verified implementation behavior.
  • Current and proposed states cannot be confused.
  • Security, data ownership, and destructive-operation boundaries are explicit.
  • Source modules and tests are linked where useful.
  • Architecture review is required when relevant modules, data flows, or deployment assumptions change.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions