docs: Add internal docs

Author: oSumAtrIX

README.md

@@ -68,6 +68,7 @@ Collection of all ReVanced documentation.
 - [💻 ReVanced CLI](./docs/revanced-cli): Documentation and usage guides for ReVanced CLI
 - [💉 ReVanced Patcher](./docs/revanced-patcher): Documentation and usage guides for ReVanced Patcher
 - [🛠️ ReVanced Development](./docs/revanced-development): Documentation to setup a development environment for ReVanced
+- [⚙️ ReVanced Internals](./docs/revanced-internals): Documentation of internal processes of ReVanced
 - [🟠 ReVanced Other](./docs/revanced-other): Miscellaneous documents used on our platforms, such as Reddit or Discord
 
 > [!WARNING]  

docs/revanced-internals/README.md

@@ -0,0 +1,14 @@
+# ⚙️ ReVanced internals
+
+Documentation about ReVanced's internal structure and workings to learn more about how it operates.
+
+## ❓ Why
+
+ReVanced is a FOSS (Free and Open Source Software) project. However, one of the largest remaining gaps is transparency regarding its internal workings. By documenting its architecture and functionality, a clearer understanding of the project is established, making it easier for contributors to engage with and improve its internal workings.
+
+## 📖 Table of contents
+
+- [Principles](principles.md)
+- [Management](management.md)
+- [Infrastructure](infrastructure.md)
+- [Finance](finance.md)

docs/revanced-internals/finance.md

@@ -0,0 +1,19 @@
+# ReVanced finance
+
+ReVanced receives financial contributions from the community in form of donations. These donations help support the ongoing development and maintenance of the project. The project is committed to transparency and accountability in its financial practices.
+
+## Sources
+
+The ReVanced website provides directions to various donation platforms:
+
+- OpenCollective: This is the main platform for collecting donations and managing financial contributions to the ReVanced project. It is used to provide transparency regarding the project's finances and to allow contributors to see how their donations are being utilized.
+- GitHub Sponsors: This platform allows users to financially support the ReVanced project directly through GitHub. However, those donations are sent to the OpenCollective account and are managed through that platform as well for transparency and accountability.
+- Cryptocurrency: The ReVanced project also accepts donations in cryptocurrency, offering an alternative for contributors who prefer digital payments. As of now, the funds are managed separately and may not have the same level of transparency as other donation methods, transactions may still be traceable through public blockchain records. So far, these funds have mostly been untouched for further development.
+
+## Treasury
+
+Funds are held in a bank account under the ReVanced organization and a crypto wallet. Access to the treasury is granted to the single lead under the least privilege principle.
+
+## Use
+
+All funds are received by ReVanced, not individuals for profit. They are used to cover infrastructure or corporate expenses. Examples include paid external services like Google Cloud for Gemini (used in Crowdin), Domain name registration, virtual phone number, mailing or fax services, US registered agent and compliance filings to the state of incorporation or the government. Before the transition into a non-profit organization, remaining funds were shared evenly across all maintainers to support their work on the project. However, under a non-profit structure, maintainers are not paid as employees due to their nature of volunteer work, but as contractors under the respective agreements. Fair compensation for their work is ensured through law and these contracts.

docs/revanced-internals/infrastructure.md

@@ -0,0 +1,68 @@
+# ReVanced infrastructure
+
+ReVanced infrastructure is simple and overseeable, relying on widely-used open-source tools and services to keep things efficient and cost-effective.
+
+## High level overview
+
+ReVanced uses public social media platforms like Discord, Reddit, Telegram, Twitter and co. to facilitate communication, collaboration and community engagement. ReVanced uses GitHub to host the source code and manage development. ReVanced has presence via its own domain. On this domain ReVanced provides a website and hosts internal and public services like ReVanced API. ReVanced relies on crucial services like Cloudflare or Oracle Cloud Infrastructure. Internal services hosted via Oracle Cloud Infrastructure include own self-hosted instances of various tools and services to keep cost minimal and maximize control. ReVanced is also incorporated in the United States. Corporate administration and governance is done internally with responsible parties of ReVanced and external legal counsel as needed. Some infrastructure also depends on financial matters (e.g. Domain name) or corporation finance (e.g. US registered agent, compliance filings to the state of incorporation or the government). For this reason ReVanced uses OpenCollective and GitHub Sponsors and a crypto wallet to fund its operations and cover expenses. For document management, an instance of Paperless-ngx is self-hosted.
+
+## Detailed overview
+
+### External services
+
+- Cloudflare (CDN, DNS, DDoS protection, Object storage with R2 (up to 10GB free) for infrastructure backups, E-Mail, Zero Trust to protect internal services)
+- SMTP2GO (E-Mail delivery service)
+- Oracle Cloud Infrastructure (Always Free services for VPS)
+- OpenCollective (Open and transparent funding)
+- GitHub (Source code hosting and collaboration platform, funds from GitHub Sponsors sent to OpenCollective)
+- Various social media platforms (Communication and community engagement)
+- Namecheap (Domain registration and management)
+- Mercury (Banking)
+- Legal and compliance services (USPTO, WIPO, Wyoming Registered Agent)
+- Crowdin (Localization and translation management)
+- Microsoft Clarity & Google Analytics (User behavior analytics)
+- Figma (Design and prototyping)
+
+### Self-hosted services
+
+- Portainer (Management of all of the self-hosted services)
+- Watchtower (Automatic container management for updates)
+- Nginx (Web server and reverse proxy)
+- Forgejo (Self-hosted Git service to ensure independence from GitHub)
+- Paperless-ngx (Document management system)
+- Vaultwarden (Self-hosted password manager)
+- ReVanced Bot (Bot for community engagement and support)
+- Wit.ai (Generative AI for ReVanced Bot)
+- ReVanced API (Internal API for ReVanced services like ReVanced Manager or ReVanced Website)
+- Duplicati (Backup volumes for self-hosted services to Cloudflare R2)
+- GoAccess (Analytics for Nginx logs)
+
+## Details
+
+ReVanced uses Oracle Cloud Free Tier services to host a Ubuntu VPS instance (with ESM and unattended upgrades enabled). Only two incoming ports are open for Nginx and OpenSSH (SSH). SSH access is hardened with key-based authentication and other security measures. All self-hosted services are managed using Docker containers via Portainer, including Nginx. Watchtower keeps them up to date. Duplicati is set up to upload volumes to Cloudflare R2. Portainer backs up itself to R2 as well. Nginx is hardened (e.g. to only allow connections from Cloudflare, preventing TLS certificate leakage to expose the IP address of the VPS, generic HTTP security headers and SSL configurations). HTTP is proxied by Cloudflare. For SSH, Cloudflare proxy is disabled, however a random subdomain name is used for security by obscurity. All HTTP services are proxied by Nginx. Vaultwarden is used for passwords and secret storage. 2FA is enforced. Passwords are randomly generated using Bitwarden. Critical services like Vaultwarden, Portainer and co. are protected behind Cloudflare Zero Trust. For external services ReVanced E-Mails are used.
+
+## Critical infrastructure and single points of failures
+
+### Account compromise
+
+- Namecheap: Affects end-users as malware could be distributed. Mitigated by code- and artifact-signing. External services can be compromised due to compromise of E-Mail accounts. Mitigated by using 2FA.
+- Cloudflare: This would reveal the VPS IP address. However the IP address can be rotated. E-Mail can be compromised again. Backups on R2 are encrypted and are not affected. Services behind Zero Trust can be compromised. This is mitigated by additional authentication.
+- Oracle Cloud: Affects end-users as malware could be distributed. Mitigated by code- and artifact-signing, user permissions and passphrase protected keys for SSH authentication. Deployed secrets and credentials can be compromised, leading to compromise of external services (e.g. ReVanced Bot Discord token).
+- Portainer: Affects all self-hosted services including ReVanced API or ReVanced Bot affecting end-users as malware could be distributed. Volumes can be compromised including deployed secrets, leading to compromise of external services. Privilege escalation could compromise the VPS.
+- Duplicati: Affects backups of volumes. Encryption keys are stored in the deployment and can be compromised as well, leading to compromise of backup data including other secrets leading to compromise of other services.
+- Vaultwarden: Affects password and secret storage leading to compromise of external services and affect end-users as malware could be distributed. Mitigated by password policies, 2FA and Cloudflare Zero Trust.
+- Social media platforms: Affects the respective platform. The community may lose trust and engagement if accounts are compromised or misused.
+
+### Supply chain attacks
+
+- GitHub: As multiple maintainers have individual permissions to push changes, malicious code can be introduced into the codebase. Mitigated by code reviews, automated testing, and monitoring for suspicious activity by public contributors Secrets from the GitHub repository can be leaked by dumping them in workflow runs leading to compromise of signing keys. Mitigated by using revokable subkeys. Malware can be re-uploaded in existing GitHub releases. Mitigated by GitHub artifact attestation and artifact-signing.
+- Oracle Cloud, Portainer, ReVanced API: These components deliver the releases to end-users. Compromise could redirect to malicious assets. Mitigated by artifact-signing.
+
+### E-Mail
+
+External services are registered with ReVanced E-Mails. Compromise of E-Mail accounts can lead to unauthorized access to these services, potentially resulting in further security incidents. Mitigated by password policies and 2FA.
+
+### Malicious intent
+
+Authorized users with extended access such as maintainers, collaborators or administrators could intentionally or unintentionally introduce vulnerabilities or malicious code into systems in reach. Mitigated by least privilege principle, access controls, code reviews, and monitoring for suspicious activity.
+

docs/revanced-internals/management.md

@@ -0,0 +1,43 @@
+# ReVanced management
+
+This documentation provides an overview of the management structure and processes within the ReVanced project.
+
+## Decisions
+
+ReVanced is maintained by a handful of maintainers. Big decisions are discussed with maintainers on Discord in a team channel. Opinions and feedback from the community are also taken into account during the decision-making process if needed. No decision is pushed without proper discussion and consensus. Sometimes discussions can be lengthy and involve multiple rounds of feedback before a final decision is reached. Often this is done asynchronously, allowing maintainers to contribute at their convenience. Not all maintainers show the same activity and not all voices are weighted equally, depending on their involvement and depth in the discussion topics. Due to the nature of an asynchronous, fast flowing chat, improper communication, or past relevant messages getting lost in the chat, sometimes misunderstandings or conflicting opinions in the decision-making process arise. If seemed useful, once a general consensus is reached, a summary of the decision and its rationale may be moved to a GitHub issue, which also is fully public for any community member to view and discuss.
+
+## GitHub
+
+GitHub is the primary platform for collaboration and code management within the ReVanced project. It is frequently used by maintainers and the community. GitHub is not used for support unlike our social media platforms to keep it focused on development and collaboration, however as a platform, the organization has a discussion set up that is reserved for support or questions. Frequently, duplicate or insufficiently detailed issues are closed to keep the repository organized. On Discord a channel is reserved for notifications from GitHub. As Discord is a central platform the maintainers use, the channel is a quick way to see updates and changes made on GitHub swiftly, however it is easy to get lost in the sheer amount of notifications, so it is important to keep track of them on a daily basis. Active issues or pull requests are easy to follow through that channel.
+
+Pull requests are reviewed until they satisfy the project's contribution guidelines and receive approval from the maintainers. Sometimes, this involves multiple feedback loops. Sometimes PRs are large or insignificant which keeps them longer in the review process. Such PRs require review and approval from multiple maintainers. Smaller PRs are sometimes merged on behalf of a single maintainer. Maintainers may also skip the PR process and directly commit changes to the target branches in case they deem a PR process unnecessary (e.g. for small or urgent changes).
+
+Spam and duplicate issues are common. Since GitHub is a central platform for both, maintainers and the community, the community often miss relevant notices or are unaware of certain practices on the platform leading to duplicate issues or spam (e.g. support requests, offtopic or heated discussions).
+
+## Social media
+
+Maintainers engage with the community on social media platforms like Discord, Telegram, Reddit and co. to discuss changes, gather feedback, or provide support. Social media is a crucial aspect of transparency and staying close to the community. It also allows for real-time communication and quick updates on project developments. All platforms are used to communicate imminent changes, updates, and important announcements to the community. On Reddit, selected moderators, some of which are maintainers of the project, manage the ReVanced subreddit. Day to day, posts are moderated. Discord is the main platform, maintainers of ReVanced use. Reddit and Telegram are heavily used by the community instead. Telegram and Twitter are rarely moderated, due to lack of maintainer activity on those platforms.
+
+## Progress
+
+From time to time, maintainers are encouraged to take up new initiatives or projects within ReVanced. Depending on the priority, size and complexity of the initiative and the maintainers capability and availability, these initiatives may be pursued individually or collaboratively. Usually this happens on Discord in the team or similar development channels such as GitHub. Specific maintainers may collaborate with others in the same area of expertise or interest to drive these initiatives forward. Sometimes, many initiatives may stale or be deprioritized if they are not actively worked on or if the maintainers involved become unavailable. In such cases it is attempted to re-evaluate the initiative's importance and either reassign it to a different maintainer or archive it for future reference.
+
+## Team structure
+
+The structure is hybrid, with a mix of hierarchical and flat elements. The team channel on Discord is accessible by all maintainers (not all maintainers are on Discord) to voice their opinions, share updates, and collaborate on projects. This setup encourages open communication and fosters community among the maintainers. Regardless some kind of hierarchy exists for top-level projects (e.g. ReVanced Manager, ReVanced Patches, ReVanced Website). Those projects are led by individual maintainers who collaborate with sub-teams in their respective areas. Cross-team collaboration is a common practice, with maintainers often working together across different projects to share knowledge and resources.
+
+## Project lead
+
+Despite the flat structure, an overall lead oversees all top-level projects, to whom the designated project leads report. The lead is responsible for ensuring alignment between projects and facilitating communication among project leads and has a stronger strategic oversight over the project. The lead participates in key decision-making processes and helps to resolve conflicts or challenges that may arise within or between projects. Regardless, all maintainers and community voices are heard and considered in the decision-making process equally to ensure a fair and democratic outcome. Weighting may be applied based on expertise, involvement, and the impact of contributions.
+
+## Lifecycle of maintainers
+
+New maintainers are spotted in-the-wild by existing maintainers or through community contributions. Once a potential new maintainer is identified depending on their contributions, interest, skill and ReVanced's needs, they are typically invited to join the team. Unlike external contributors, maintainers are directly tasked with specific responsibilities and have a greater level of access and insight to the project. Some of the resources they are granted access to include:
+
+- Discord team role
+- ReVanced E-Mail address
+- ReVanced GitHub access through a GitHub organization membership and team
+- A Vaultwarden account (usually with access to their own vault only)
+- Introductories into ReVanced's processes and internals
+
+Removal of maintainers occurs if they become inactive, unavailable, decide to leave on their own basis, due to organizational requirements or needs or if the position is no longer a good fit. The decision to remove a maintainer is proposed under a reasonable basis and is made collectively by the existing maintainers, ensuring that all voices are heard and considered in the process, including that of the maintainer in question. Under a reasonable counterproposal, the maintainer may also be given the opportunity to transition to a different role or responsibility within the organization if appropriate. With a growing team, it is also increasingly complex and challenging to manage, which is why it is important to ReVanced to have a purposeful amount of maintainers to ensure effective collaboration and project progress.