LibreSign · vitormattos · Oct 3, 2026 · Oct 3, 2026 · Oct 3, 2026
diff --git a/developer_manual/architecture.rst b/developer_manual/architecture.rst
@@ -0,0 +1,88 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: CC-BY-3.0
+
+Architecture and code map
+=========================
+
+LibreSign is a Nextcloud application. This page is the canonical starting point
+for understanding where responsibilities live before changing code.
+
+Use the application repository as the source of truth for current class names,
+APIs and implementation details:
+
+`LibreSign/libresign <https://github.com/LibreSign/libresign>`_.
+
+Repository map
+--------------
+
+The main application areas are:
+
+``lib/``
+   PHP backend code. Controllers expose HTTP/OCS behavior, services contain
+   application logic and orchestration, database classes persist application
+   state, and handlers contain specialized signing/certificate behavior.
+
+``src/``
+   Vue and TypeScript frontend code.
+
+``tests/php/``
+   PHP unit tests.
+
+``tests/integration/``
+   Integration scenarios and their support code.
+
+``src/tests/``
+   Frontend unit tests.
+
+``playwright/``
+   Browser/end-to-end test support where present in the current application
+   repository.
+
+``appinfo/``
+   Nextcloud application metadata and route/configuration declarations.
+
+``3rdparty/``
+   Scoped third-party dependencies. Follow the instructions in that directory
+   before changing it.
+
+Responsibility boundaries
+-------------------------
+
+Backend enforcement
+~~~~~~~~~~~~~~~~~~~
+
+Permissions, validation, policy resolution and other security-sensitive
+business rules must be enforced by the backend. Frontend checks may improve the
+user experience, but they are not an authorization boundary.
+
+Generated and vendored content
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Do not edit generated translations, generated API/type output or vendored
+dependencies as if they were normal source files. Change their source contract
+and regenerate them using the workflow documented by the application
+repository.
+
+Signing and document integrity
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Changes affecting document signing, PDF validation, certificates, cryptographic
+policy, authorization or persisted audit state require focused regression and
+negative tests at the affected trust boundary.
+
+Nextcloud integration
+~~~~~~~~~~~~~~~~~~~~~
+
+Prefer public Nextcloud OCP APIs and the repository's existing integration
+patterns. Before introducing a workaround for an upstream change, verify the
+supported Nextcloud version and current upstream contract.
+
+Where to go next
+----------------
+
+- :doc:`getting-started/development-environment/index` for setting up a
+  development runtime.
+- :doc:`getting-started/tests` for testing and validation.
+- :doc:`development-workflow` for the normal issue-to-pull-request workflow.
+- :doc:`api/index` for the public API.
+- :doc:`release-process` for release operations.
diff --git a/developer_manual/development-workflow.rst b/developer_manual/development-workflow.rst
@@ -0,0 +1,86 @@
+.. SPDX-FileCopyrightText: 2026 LibreCode coop and contributors
+.. SPDX-License-Identifier: CC-BY-3.0
+
+Development workflow
+====================
+
+This page describes the durable contribution workflow for LibreSign. Repository
+instructions such as ``AGENTS.md`` may add operational constraints for a
+particular tool, but they should point back to this documentation instead of
+duplicating it.
+
+Choose and understand the work
+------------------------------
+
+Start from a GitHub issue whenever possible. Before implementing it:
+
+- verify that the issue still matches the current code;
+- check for existing pull requests or duplicate work;
+- identify acceptance criteria, exclusions and real prerequisites;
+- keep unrelated improvements out of the same change.
+
+Large outcomes should be split into independently reviewable issues when useful.
+Use blocking relationships only for real prerequisites.
+
+Prepare the environment
+-----------------------
+
+Use the supported development environment described in
+:doc:`getting-started/development-environment/index`.
+
+The environment implementation may evolve, but contributors should not need to
+maintain multiple independent Nextcloud Docker topologies for the same project.
+
+Implement a focused change
+--------------------------
+
+Prefer the smallest coherent change that satisfies the issue.
+
+Follow the current application architecture and contribution rules from the
+base branch. Avoid unrelated refactors, dependency upgrades and formatting
+churn unless they are required for the requested outcome.
+
+Validate the behavior
+---------------------
+
+Use :doc:`getting-started/tests` to choose the relevant test path.
+
+Prefer a focused regression test that fails under the unwanted behavior when
+practical. Run narrow checks first, then broaden according to the changed
+surface and current CI requirements.
+
+Record which commands actually ran and which checks could not be run. A focused
+test does not prove the whole project is green.
+
+Review the final diff
+---------------------
+
+Before opening a pull request:
+
+- inspect every changed file for unrelated changes;
+- compare the result with the issue acceptance criteria;
+- check error paths, permissions and compatibility where relevant;
+- verify generated files and documentation when the changed contract requires
+  them.
+
+Commit and open the pull request
+--------------------------------
+
+Follow :doc:`getting-started/commits` for commit requirements and DCO.
+
+Keep the pull request focused and make validation evidence easy to review:
+reference the issue, summarize material implementation choices, list checks that
+actually ran and describe known limitations when relevant.
+
+A pull request remains subject to the repository's current review, CI and
+branch policies.
+
+After review or CI feedback
+---------------------------
+
+Re-evaluate feedback against the latest branch state before changing code.
+When CI fails, identify the causal failure before adding retries, sleeps,
+dependency pins or suppressions.
+
+Follow-up work that is useful but not required for the current issue should be
+tracked separately instead of expanding the pull request indefinitely.
diff --git a/developer_manual/getting-started/index.rst b/developer_manual/getting-started/index.rst
@@ -2,10 +2,13 @@
 Getting started
 ===============
 
+Use these pages for the practical setup and contribution prerequisites. For the
+overall issue-to-pull-request process, see :doc:`../development-workflow`.
+
 .. toctree::
    :maxdepth: 2
 
    branch-policies
    development-environment/index
    tests
-   commits
+   commits
diff --git a/developer_manual/index.rst b/developer_manual/index.rst
@@ -3,32 +3,48 @@
 Developer manual
 ================
 
-Thank you for your interest in contributing to LibreSign!
-
-There are many ways to help our project:
-
-- Write code or fix bugs  
-- Test and reproduce reported issues  
-- Improve the documentation  
-- Translate to other languages  
-- Share the security and privacy the word  
-- Give a ⭐ on `GitHub <https://github.com/LibreSign/libresign>`_  
-
-If you want to go further, you can also support LibreSign through  
+Thank you for your interest in contributing to LibreSign.
+
+This manual is the canonical source for durable LibreSign developer knowledge.
+Repository-local guidance may point here for architecture, environment, testing
+and contribution workflows instead of duplicating those topics.
+
+Start here
+----------
+
+- :doc:`architecture` — understand the application boundaries and code map.
+- :doc:`getting-started/development-environment/index` — prepare a development
+  runtime.
+- :doc:`development-workflow` — follow work from an issue to a reviewed pull
+  request.
+- :doc:`getting-started/tests` — choose and run the appropriate validation.
+- :doc:`api/index` — work with the public API.
+- :doc:`release-process` — maintain and publish releases.
+
+There are many ways to help the project:
+
+- Write code or fix bugs.
+- Test and reproduce reported issues.
+- Improve the documentation.
+- Translate to other languages.
+- Help improve security and privacy.
+- Give LibreSign a star on
+  `GitHub <https://github.com/LibreSign/libresign>`_.
+
+You can also support LibreSign through
 `GitHub Sponsors <https://github.com/sponsors/LibreSign/>`_.
 
-We provide professional support for companies as well.  
-
-For services or partnerships, please `contact us <https://libresign.coop/#contact>`_.
-
-Here you will find all the documentation for developers.
+For professional services or partnerships,
+`contact us <https://libresign.coop/#contact>`_.
 
 .. toctree::
    :maxdepth: 2
    :hidden:
 
    prologue/index
+   architecture
    getting-started/index
+   development-workflow
    api/index
    translation
    requesting-features