docs: Docusaurus

.github/workflows/deploy-docs.yml

@@ -0,0 +1,45 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+        working-directory: docs
+
+      - name: Build website
+        run: npm run build
+        working-directory: docs
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/build
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+yarn
+```
+
+## Local Development
+
+```bash
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```bash
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+Using SSH:
+
+```bash
+USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

docs/docs/functional/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Functional Documentation",
+    "position": 2,
+    "link": {
+        "type": "generated-index",
+        "description": "How it works under-the-hood when it's not visible to the user."
+    }
+}

docs/docs/functional/chat-management.md

@@ -0,0 +1,10 @@
+# Full Chat Management (Under-the-hood)
+
+Full Chat Management relies on the interaction between the `TelegramChatManageAction` and the background workers.
+
+## Key Actions
+- `set_control_level`: Updates the database state and triggers initial indexing if necessary.
+- `refresh_participants`: Orchestrates the full synchronization of the chat member list.
+
+## Database Consistency
+We use transactional sessions to ensure that participant states are always consistent across refreshes.

docs/docs/functional/indexers.md

@@ -0,0 +1,9 @@
+# Indexers
+
+Indexers are background processes that synchronize the state of Telegram chats with the local database.
+
+## Architecture
+Indexers run as Celery tasks and use the Telegram API to fetch member lists and updates.
+
+- **Full Indexer**: Performs a complete scan of the chat's participants.
+- **Incremental Indexer**: Listens for join/leave events to keep the database up-to-date.

docs/docs/functional/join-requests.md

@@ -0,0 +1,9 @@
+# Join Requests Processing
+
+When a user requests to join a private chat, Access Tool evaluates them based on active rules.
+
+## Process Flow
+1. User clicks "Join" on Telegram.
+2. Telegram sends a `chat_join_request` update to the bot.
+3. Access Tool backend checks the user against the chat's rules.
+4. If approved, the request is accepted; otherwise, it is ignored or denied.

docs/docs/technical/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "Technical Documentation",
+    "position": 3,
+    "link": {
+        "type": "generated-index",
+        "description": "API reference, architecture guidelines, etc."
+    }
+}

docs/docs/technical/api-reference.md

@@ -0,0 +1,18 @@
+# API Reference
+
+The Access Tool provides a RESTful API for management and integration.
+
+## Base URL
+`/api/v1`
+
+## Authentication
+Bearer Token (JWT) is required for most endpoints.
+
+## Main Endpoints
+- `GET /chats`: List all managed chats.
+- `POST /chats`: Add a new chat.
+- `GET /chats/{id}/rules`: List rules for a chat.
+- `PUT /chats/{id}/control`: Update control level.
+
+> [!NOTE]
+> Detailed OpenAPI documentation is available at `/docs` (Swagger) and `/redoc` on the running instance.

docs/docs/technical/architecture.md

@@ -0,0 +1,14 @@
+# Architecture
+
+Access Tool is designed as a modular monolith with a clear separation between the API, core logic, and background workers.
+
+## Layers
+- **API**: FastAPI endpoints.
+- **Actions**: High-level business logic orchestration.
+- **Services**: Database CRUD operations.
+- **Models**: SQLAlchemy database models.
+
+## Infrastructure
+- **PostgreSQL**: Primary data store.
+- **Redis**: Task queue and caching.
+- **Celery**: Distributed task processing.

docs/docs/user-guide/_category_.json

@@ -0,0 +1,8 @@
+{
+    "label": "User Guide",
+    "position": 1,
+    "link": {
+        "type": "generated-index",
+        "description": "Instructions on how to use features available and visible to users."
+    }
+}

docs/docs/user-guide/chat-management.md

@@ -0,0 +1,11 @@
+# Full Chat Management
+
+The Full Chat Management feature allows you to control all aspects of a chat's access rules and participant monitoring.
+
+## Features
+- **Access Control**: Enable/Disable entry for new users.
+- **Participant Indexing**: Keep track of all users currently in the chat.
+- **Rule Enforcement**: Automatically apply rules to existing and new members.
+
+## How to use
+Select a chat from the dashboard and click on "Manage". From here, you can toggle "Full Control" mode.

docs/docs/user-guide/configuring-chat.md

@@ -0,0 +1,11 @@
+# Configuring New Chat
+
+To configure a new chat in the Access Tool, follow these steps:
+
+1. Navigate to the Admin Dashboard.
+2. Click on the "Add Chat" button.
+3. Provide the Telegram Chat ID or Username.
+4. Set the initial visibility and control levels.
+
+> [!NOTE]
+> Ensure the bot has administrative privileges in the chat you are adding.

docs/docs/user-guide/configuring-rules.md

@@ -0,0 +1,13 @@
+# Configuring New Rules
+
+Rules define who is allowed to enter or stay in a chat.
+
+## Types of Rules
+- **Whitelist**: Specify users or groups that are always allowed.
+- **Blacklist**: Specify users or groups that are never allowed.
+- **External Source**: Fetch a list of allowed users from an external API or file.
+
+## Creating a Rule
+1. Go to the "Rules" section for a specific chat.
+2. Click "Add Rule".
+3. Select the rule type and provide the necessary configuration (e.g., URL for external source).

docs/docusaurus.config.ts

@@ -0,0 +1,124 @@
+import { themes as prismThemes } from 'prism-react-renderer';
+import type { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
+
+const config: Config = {
+  title: 'Access Tool',
+  tagline: 'Functional, Technical and Product Documentation',
+  favicon: 'img/logo.svg',
+
+  // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future
+  future: {
+    v4: true, // Improve compatibility with the upcoming Docusaurus v4
+  },
+
+  // Set the production url of your site here
+  url: 'https://OpenBuilders.github.io',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: '/access-tool/',
+
+  // GitHub pages deployment config.
+  // If you aren't using GitHub pages, you don't need these.
+  organizationName: 'OpenBuilders', // Usually your GitHub org/user name.
+  projectName: 'access-tool', // Usually your repo name.
+  deploymentBranch: 'gh-pages',
+  trailingSlash: false,
+
+  onBrokenLinks: 'throw',
+
+  // Even if you don't use internationalization, you can use this field to set
+  // useful metadata like html lang. For example, if your site is Chinese, you
+  // may want to replace "en" with "zh-Hans".
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebars.ts',
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          editUrl:
+            'https://github.com/OpenBuilders/access-tool/tree/main/docs/',
+        },
+        blog: false,
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    // Replace with your project's social card
+    image: 'img/docusaurus-social-card.jpg',
+    colorMode: {
+      respectPrefersColorScheme: true,
+    },
+    navbar: {
+      title: 'Access Tool',
+      logo: {
+        alt: 'Access Tool Logo',
+        src: 'img/logo.svg',
+      },
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'tutorialSidebar',
+          position: 'left',
+          label: 'Documentation',
+        },
+        {
+          href: 'https://github.com/OpenBuilders/access-tool',
+          label: 'GitHub',
+          position: 'right',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          title: 'Docs',
+          items: [
+            {
+              label: 'User Guide',
+              to: '/docs/user-guide/configuring-chat',
+            },
+            {
+              label: 'Functional',
+              to: '/docs/functional/indexers',
+            },
+            {
+              label: 'Technical',
+              to: '/docs/technical/architecture',
+            },
+          ],
+        },
+        {
+          title: 'Community',
+          items: [
+            {
+              label: 'GitHub',
+              href: 'https://github.com/OpenBuilders/access-tool',
+            },
+          ],
+        },
+      ],
+      copyright: `Copyright © ${new Date().getFullYear()} OpenBuilders. Built with Docusaurus.`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;