From 8dc030936556c84ff3f265b763327e1c52306842 Mon Sep 17 00:00:00 2001 From: Guido X Jansen Date: Tue, 10 Feb 2026 02:11:44 +0100 Subject: [PATCH] docs: add README, PR template, and security policy - Professional README with quick start and tech stack - PR template with checklist - Security policy with vulnerability reporting process Prepares repo for open source contributions --- .github/PULL_REQUEST_TEMPLATE.md | 69 ++++++++++++ .github/SECURITY.md | 37 +++++++ README.md | 180 +++++++++++++++++++++++++++++++ 3 files changed, 286 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/SECURITY.md create mode 100644 README.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..af93ade --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,69 @@ +## Description + + + +Closes # + +## Type of Change + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Refactor (no functional changes) +- [ ] Dependency update +- [ ] CI/CD changes + +## Testing + + + +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] Manual testing performed +- [ ] Accessibility tested (if UI changes) +- [ ] Tested in staging environment +- [ ] All tests pass locally (`pnpm test`) + +**Test coverage:** + +## Checklist + +- [ ] Code follows conventional commit format +- [ ] Self-review completed (read own diff on GitHub) +- [ ] No TypeScript errors (`pnpm typecheck`) +- [ ] No ESLint warnings (`pnpm lint`) +- [ ] Documentation updated (if applicable) +- [ ] Database migration included (if schema changed) +- [ ] Breaking changes documented below (if applicable) +- [ ] CI checks pass +- [ ] No secrets or credentials in code + +## Breaking Changes + + + +**None** / + +## Screenshots/Logs (if applicable) + + + +## Additional Context + + + +## Reviewer Checklist + + + +- [ ] Code quality meets standards +- [ ] Tests are meaningful and cover edge cases +- [ ] Security considerations addressed +- [ ] Performance impact acceptable +- [ ] Accessibility compliant (if UI) +- [ ] Documentation clear and complete diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..415a89a --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,37 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +| ------- | ------------------ | +| 1.x | :white_check_mark: | +| < 1.0 | :x: | + +## Reporting a Vulnerability + +**Do not open a public issue for security vulnerabilities.** + +Instead, use GitHub's private vulnerability reporting: + +1. Go to the repository +2. Click "Security" tab +3. Click "Report a vulnerability" +4. Fill in the details + +Or email: security@atgora.forum (TBD - will be set up in Phase 2) + +We will respond within 72 hours with next steps. + +## Security Practices + +- All commits must be GPG signed +- Dependencies updated weekly via Dependabot +- CI runs security scans on every PR +- OWASP Top 10 compliance verified + +## Disclosure Policy + +We follow responsible disclosure: +- 90 days before public disclosure +- Credit given to reporter (if desired) +- CVE assigned when applicable diff --git a/README.md b/README.md new file mode 100644 index 0000000..3cc6c3e --- /dev/null +++ b/README.md @@ -0,0 +1,180 @@ +# atgora-api + +**AppView backend for ATgora forums** + +[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL%203.0-blue.svg)](https://opensource.org/licenses/AGPL-3.0) +[![Node.js](https://img.shields.io/badge/node-24%20LTS-brightgreen)](https://nodejs.org/) +[![TypeScript](https://img.shields.io/badge/typescript-5.x-blue)](https://www.typescriptlang.org/) + +--- + +## 🚧 Status: Pre-Alpha Development + +This is the AppView backend for ATgora - community forums built on the AT Protocol. + +**Current phase:** Planning complete, implementation starting Q1 2026 + +--- + +## What is this? + +The atgora-api is the core engine that powers every ATgora forum. It: + +- **Subscribes to the AT Protocol firehose** - Indexes forum records in real-time +- **Exposes a REST API** - All forum operations (topics, replies, reactions, search, moderation) +- **Manages authentication** - OAuth integration with AT Protocol PDS providers +- **Handles moderation** - Forum-level and global content filtering +- **Enables cross-forum features** - Reputation, aggregation, search across instances + +**Two operating modes:** +- **Single-forum mode** - Indexes one community +- **Global mode** - Aggregates ALL ATgora forums (like atgora.forum) + +--- + +## Tech Stack + +| Component | Technology | +|-----------|-----------| +| Runtime | Node.js 24 LTS, TypeScript (strict mode) | +| Framework | Fastify | +| Database | PostgreSQL 16 + pgvector (semantic search) | +| Cache | Valkey | +| Protocol | @atproto/api, @atproto/oauth-client-node, @atproto/tap | +| ORM | Drizzle | +| Validation | Zod | +| Testing | Vitest, Supertest | +| Logging | Pino | +| Monitoring | Sentry | + +--- + +## Key Features (Planned MVP) + +- **Firehose subscription** - Tap-based subscription to Bluesky relay, filtered for `forum.atgora.*` records +- **Real-time indexing** - Topics, replies, reactions indexed to PostgreSQL +- **OAuth authentication** - Works with any AT Protocol PDS (Bluesky, self-hosted, etc.) +- **Full-text + semantic search** - PostgreSQL tsvector + pgvector hybrid search +- **Content maturity filtering** - Age-appropriate defaults, user preferences, per-forum overrides +- **Cross-posting** - Share topics to Bluesky/Frontpage automatically +- **Moderation tools** - Lock/pin/delete, ban users, moderation logs +- **API documentation** - Auto-generated OpenAPI spec served at `/docs` + +--- + +## Prerequisites + +- Node.js 24 LTS +- pnpm +- Docker + Docker Compose (for PostgreSQL + Valkey) +- AT Protocol PDS access (Bluesky or self-hosted) + +--- + +## Quick Start + +**Clone and install:** +```bash +git clone https://github.com/atgora-forum/atgora-api.git +cd atgora-api +pnpm install +``` + +**Start dependencies:** +```bash +docker compose -f docker-compose.dev.yml up -d +``` + +**Configure environment:** +```bash +cp .env.example .env +# Edit .env with your settings +``` + +**Run development server:** +```bash +pnpm dev +``` + +**Run tests:** +```bash +pnpm test +pnpm lint +pnpm typecheck +``` + +--- + +## API Documentation + +When running, interactive API docs are available at: + +**Local:** `http://localhost:3000/docs` +**Production:** `https://api.atgora.forum/docs` + +OpenAPI spec: `GET /api/openapi.json` + +--- + +## Development + +See [CONTRIBUTING.md](../CONTRIBUTING.md) for: +- Branching strategy +- Commit message format +- Testing requirements +- Code review process + +**Key standards:** +- TypeScript strict mode (no `any`, no `@ts-ignore`) +- All endpoints validate input (Zod schemas) +- All user content sanitized (DOMPurify) +- Test-driven development (TDD) +- Conventional commits enforced + +--- + +## Deployment + +**Production deployment via Docker:** +```bash +docker pull ghcr.io/atgora-forum/atgora-api:latest +``` + +See [atgora-deploy](https://github.com/atgora-forum/atgora-deploy) for full deployment templates. + +--- + +## Documentation + +- **API Reference:** Served at `/docs` (auto-generated from code) +- **User Guides:** [atgora.forum/docs](https://atgora.forum/docs) (coming soon) +- **Architecture:** [PRD](https://github.com/atgora-forum/atgora-api/blob/main/docs/prd.md) + +--- + +## License + +**AGPL-3.0** - Protects the core. Competitors running hosted services must share their changes. + +See [LICENSE](LICENSE) for full terms. + +--- + +## Related Repositories + +- **[atgora-web](https://github.com/atgora-forum/atgora-web)** - Forum frontend (Next.js) +- **[atgora-lexicons](https://github.com/atgora-forum/atgora-lexicons)** - AT Protocol schemas +- **[atgora-deploy](https://github.com/atgora-forum/atgora-deploy)** - Deployment templates +- **[Organization](https://github.com/atgora-forum)** - All repos + +--- + +## Community + +- 🌐 **Website:** [atgora.forum](https://atgora.forum) (coming soon) +- 💬 **Discussions:** [GitHub Discussions](https://github.com/orgs/atgora-forum/discussions) +- 🐛 **Issues:** [Report bugs](https://github.com/atgora-forum/atgora-api/issues) + +--- + +© 2026 ATgora. Licensed under AGPL-3.0. -- 2.51.2