docs(master): add architectural reference README

[lgsilva3087]

The master server is one of the largest components in the codebase. A high-level architectural reference helps new contributors to understand how the major subsystems relate to each other before diving into the code.

[gemini-code-assist]

Summary of Changes

Hello @lgsilva3087, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a comprehensive architectural reference document for the master server component of SaunaFS. This README aims to provide new contributors with a high-level understanding of the master server's structure, core functionalities, and inter-component relationships before they delve into the codebase.

Highlights

• Master Server Overview: Detailed the role of the sfsmaster as the central metadata authority, explaining its two runtime personalities: Master (active) and Shadow (hot-standby).
• Code Organization: Explained the flat directory structure and how files are grouped by filename prefix, each corresponding to a logical subsystem (e.g., filesystem_*, matoclserv*).
• Core Data Model: Described the FilesystemMetadata instance, its key members like nodeHash and inodePool, and the FSNode type hierarchy for filesystem objects.
• Filesystem Operations: Outlined the two-layer interface hierarchy for operations (IFilesystemOperations and IFilesystemNodeOperations) and the role of FsContext and FilesystemOperationContext.
• Chunk Management: Covered the responsibilities of chunk state management, including lifecycle, location tracking, replication decisions, and server selection.
• Network Servers: Documented the five types of peer communication using the mato*serv naming convention (FUSE clients, Chunkservers, Metaloggers/Shadows, Notifier clients, Active master).
• Metadata Persistence: Explained the two mechanisms for durability: full metadata snapshots (via IMetadataBackend) and the changelog (Write-Ahead Log).
• KV Store Backend: Introduced FoundationDB as an alternative distributed metadata storage option, detailing the IKVConnector interface and key prefix conventions.
• Task Manager and Async Tasks: Described the TaskManager for breaking down long-running operations into incremental tasks to maintain responsiveness.
• Periodic Operations: Listed various maintenance routines that run on timer-driven or per-loop schedules, such as file integrity tests, trash cleanup, and chunk maintenance.
• Initialization Sequence: Provided an ordered list of startup steps orchestrated by RunTab arrays in init.h.
• Key Design Patterns: Highlighted important architectural patterns like strategy/interface-based extensibility, observer/signal pattern, global process state, conditional compilation, incremental stat propagation, and cooperative multitasking.

Changelog

• src/master/README.md
  • Added a new architectural reference document for the master server.

Activity

• No activity to report yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This is an excellent and much-needed architectural reference for the master server. The document is comprehensive, well-structured, and provides a clear overview of the major subsystems, data models, and design patterns. This will be incredibly valuable for new contributors to get up to speed with this complex part of the codebase. I've only found a very minor formatting suggestion in the code organization table. Great work!

[Copilot]

Pull request overview

This pull request adds comprehensive architectural documentation for the master server component, the central metadata authority in a SaunaFS cluster. The documentation helps new contributors understand the major subsystems and their relationships before diving into the code.

Changes:

• Added a detailed architectural reference document (README.md) to the master server directory covering code organization, data models, network servers, persistence mechanisms, and design patterns

[rolysr]

Very nice to start adding these reference docs. Consider my comments.