diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 015f084..954f60a 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,192 +1,54 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Changelog +== Changelog -All notable changes to this project will be documented in this file. +All notable changes to `+social-media-polygraph+` will be documented in +this file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. -== [Unreleased] +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. -=== Planned -- Real fact-checking API integrations (Google Fact Check, Snopes, PolitiFact) -- Multi-language support -- Real-time claim monitoring -- Webhook support for notifications -- PDF/CSV export functionality -- Enhanced ML models with fine-tuning -- Mobile applications -- Advanced analytics dashboard +=== [Unreleased] -== [0.1.0] - 2024-01-15 +==== Added -=== Added +* feat: import foundation from social-media-tools/polygraph fork -==== Backend -- FastAPI RESTful API with async support -- ArangoDB multi-model database integration - - Document storage for claims, sources, users - - Graph relationships for knowledge graph - - Collections: claims, sources, fact_checks, users, api_keys -- XTDB temporal database for claim history tracking -- Dragonfly cache for high-performance caching -- NLP pipeline with spaCy - - Entity extraction - - Sentiment analysis with TextBlob - - Text complexity analysis - - Language detection -- Credibility scoring algorithm - - Source credibility scoring - - Claim credibility scoring - - Bias detection -- Fact-checking service framework (mock implementations) -- JWT authentication system -- API key management -- Rate limiting with slowapi -- Prometheus metrics integration -- Comprehensive error handling -- Logging with loguru -- Test suite with pytest - - Unit tests for NLP processor - - Unit tests for credibility scorer - - Integration tests for API endpoints - - Test fixtures and mocks +==== Fixed -==== Frontend -- React 18 application with TypeScript -- Vite build system -- TailwindCSS styling -- React Query for data fetching -- React Router for navigation -- Pages: - - Home page with feature overview - - Verify page for claim submission - - Claim detail page with full analysis - - About page with project information -- Components: - - Layout with header and footer - - VerificationResult display component -- API client service -- TypeScript types and interfaces -- Responsive design -- Form validation with react-hook-form - -==== Browser Extension -- Manifest V3 Chrome/Firefox extension -- Background service worker -- Content scripts for social media integration - - Twitter/X support - - Facebook placeholder - - Instagram placeholder -- Popup interface for quick verification -- Context menu integration -- Cross-platform compatibility - -==== Infrastructure -- Podman containerization - - Backend Containerfile with multi-stage build - - Frontend Containerfile with nginx -- Podman Compose orchestration - - ArangoDB service - - XTDB service - - Dragonfly service - - Backend API service - - Frontend service -- GitHub Actions CI/CD - - Backend tests and linting - - Frontend tests and type checking - - Container building - - Security scanning with Trivy - - Deployment workflow -- Development scripts - - start-dev.sh - - stop-dev.sh +* fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build +drift) (#15) +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): rsr-antipattern.yml duplicate heredoc (#14) ==== Documentation -- Comprehensive README with quick start -- API documentation (docs/API.md) -- Architecture documentation (docs/ARCHITECTURE.md) -- Deployment guide (docs/DEPLOYMENT.md) -- Contributing guidelines (CONTRIBUTING.md) -- Security policy (SECURITY.md) -- Code of Conduct (CODE_OF_CONDUCT.md) -- Maintainers guide (MAINTAINERS.md) -- Development summary -- MIT License -- .gitignore for Python, Node, containers - -==== Configuration -- Environment variable configuration -- Poetry dependency management for Python -- npm package management for frontend -- TypeScript configuration -- ESLint and Prettier setup -- Pytest configuration -- Docker/Podman health checks - -=== Security -- JWT token-based authentication -- bcrypt password hashing -- API key authentication support -- Rate limiting (100 req/min default) -- CORS configuration -- Input validation with Pydantic -- SQL injection prevention (NoSQL) -- XSS prevention in frontend -- Security headers in nginx -- Non-root container users -- Secrets management via environment variables - -=== Developer Experience -- Type safety - - Python type hints throughout - - Full TypeScript typing in frontend -- Code quality tools - - Black code formatting - - Ruff linting - - mypy type checking - - ESLint for TypeScript -- Testing infrastructure - - pytest with coverage - - Test fixtures and mocks - - Integration test framework -- Development workflow - - Hot reload in development - - Fast builds with Vite - - One-command startup -- Documentation - - Inline code comments - - API documentation - - Architecture diagrams - - Deployment guides - -== Version History - -=== Version Numbering - -We use [Semantic Versioning](https://semver.org/): - -- **MAJOR** version for incompatible API changes -- **MINOR** version for backwards-compatible functionality additions -- **PATCH** version for backwards-compatible bug fixes - -=== Release Schedule - -- **Major releases**: Annually (breaking changes) -- **Minor releases**: Quarterly (new features) -- **Patch releases**: As needed (bug fixes, security) -=== Upgrade Guides +* docs: record tech-debt audit findings (2026-05-26) (#26) +* docs(readme): add SPDX header, OSSF and GWF badges; fix license badge +to PMPL -For breaking changes, see `docs/UPGRADE.md` (to be created). +==== CI -== Contributing +* ci: bump actions/upload-artifact SHA to current v4 (#13) +* ci(antipattern): fix top-level dir matching + benchmarks/lsp/bench +filename allowlists (#9) +* ci(antipattern): TS check reads .claude/CLAUDE.md exemption table (#8) +* ci(antipattern): broaden TS allowlist (cli/, mod.ts, lsp-server, +_vscode_, deno-*) (#7) +* ci(antipattern): allowlist legit TS bridge/adapter paths (#6) -See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute to this project. +=== Pre-history -== Links +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. -- [Repository](https://github.com/hyperpolymath/social-media-polygraph) -- [Issue Tracker](https://github.com/hyperpolymath/social-media-polygraph/issues) -- [Security Policy](SECURITY.md) -- [Code of Conduct](CODE_OF_CONDUCT.md) +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 6916ba8..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,50 +0,0 @@ - - -# Changelog - -All notable changes to `social-media-polygraph` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat: import foundation from social-media-tools/polygraph fork - -### Fixed - -- fix(ci): sync hypatia-scan.yml to canonical (kill cd-scanner build drift) (#15) -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): rsr-antipattern.yml duplicate heredoc (#14) - -### Documentation - -- docs: record tech-debt audit findings (2026-05-26) (#26) -- docs(readme): add SPDX header, OSSF and GWF badges; fix license badge to PMPL - -### CI - -- ci: bump actions/upload-artifact SHA to current v4 (#13) -- ci(antipattern): fix top-level dir matching + benchmarks/lsp/bench filename allowlists (#9) -- ci(antipattern): TS check reads .claude/CLAUDE.md exemption table (#8) -- ci(antipattern): broaden TS allowlist (cli/, mod.ts, lsp-server, *vscode*, deno-*) (#7) -- ci(antipattern): allowlist legit TS bridge/adapter paths (#6) - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..ff3f3db --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +Squisher Corpus a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |j.d.a.jewell@open.ac.uk |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *48 hours* +. The maintainers will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a maintainers member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The maintainers will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* j.d.a.jewell@open.ac.uk with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different maintainers member than the +original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/squisher-corpus/discussions[Discussion] +(for general questions) +* Email j.d.a.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 8267cd4..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,327 +0,0 @@ -# Code of Conduct - - - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in Squisher Corpus a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | j.d.a.jewell@open.ac.uk | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **48 hours** -2. The maintainers will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a maintainers member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The maintainers will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** j.d.a.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different maintainers member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/squisher-corpus/discussions) (for general questions) -- Email j.d.a.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index eb045d6..7ebd521 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,20 +1,109 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Contributing Guide +== Clone the repository -== Getting Started +git clone https://github.com/hyperpolymath/social-media-polygraph.git cd +social-media-polygraph -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Nix (recommended for reproducibility) -== Commit Guidelines +nix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create social-media-polygraph-dev toolbox enter +social-media-polygraph-dev # Install dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +social-media-polygraph/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ +# Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter +2) ├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter +2) ├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix # Nix flake +(Perimeter 1) └── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/social-media-polygraph/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/social-media-polygraph/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/social-media-polygraph/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/social-media-polygraph/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index a992765..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/social-media-polygraph.git -cd social-media-polygraph - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create social-media-polygraph-dev -toolbox enter social-media-polygraph-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -social-media-polygraph/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/social-media-polygraph/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/social-media-polygraph/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/social-media-polygraph/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/social-media-polygraph/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/DEVELOPMENT_SUMMARY.adoc b/DEVELOPMENT_SUMMARY.adoc new file mode 100644 index 0000000..504aa87 --- /dev/null +++ b/DEVELOPMENT_SUMMARY.adoc @@ -0,0 +1,363 @@ +== Development Summary + +*Generated:* Autonomous development session *Status:* ✅ Complete +*Commits:* 2 (Initial CLAUDE.md + Full implementation) *Files Created:* +73 *Lines of Code:* ~7,400 + +=== What Was Built + +I’ve created a *complete, production-ready AI-powered fact-checking +platform* called Social Media Polygraph. This is a comprehensive system +for verifying claims and detecting misinformation on social media. + +=== 🎯 Key Features Implemented + +==== Backend (Python/FastAPI) + +* ✅ Full RESTful API with async FastAPI +* ✅ ArangoDB multi-model database (documents + graph) +* ✅ XTDB temporal database for claim history +* ✅ Dragonfly high-performance cache +* ✅ Advanced NLP with spaCy (entity extraction, sentiment analysis) +* ✅ Credibility scoring algorithm +* ✅ Fact-checking service integrations +* ✅ JWT authentication + API key management +* ✅ Rate limiting and security +* ✅ Comprehensive test suite + +==== Frontend (React/TypeScript) + +* ✅ Modern React 18 with TypeScript +* ✅ Responsive UI with TailwindCSS +* ✅ Claim verification interface +* ✅ Results visualization +* ✅ Temporal history display +* ✅ React Query for data fetching +* ✅ Full type safety + +==== Browser Extension + +* ✅ Chrome/Firefox compatible +* ✅ In-context verification on Twitter/X, Facebook, Instagram +* ✅ Popup interface +* ✅ Context menu integration +* ✅ Background processing + +==== Infrastructure + +* ✅ Podman containerization +* ✅ Multi-container orchestration +* ✅ Production deployment configs +* ✅ CI/CD with GitHub Actions +* ✅ Comprehensive documentation + +=== 📊 Project Statistics + +.... +Backend: + - Python files: 23 + - Test files: 5 + - API endpoints: 8+ + - Database collections: 8 + - ML/NLP modules: 2 + +Frontend: + - React components: 7 + - Pages: 4 + - TypeScript files: 12 + - API services: 1 + +Infrastructure: + - Containerfiles: 2 + - Compose files: 1 + - CI/CD workflows: 2 + - Scripts: 2 + +Documentation: + - README: Comprehensive + - API docs: Complete + - Architecture: Detailed + - Deployment: Production-ready +.... + +=== 🚀 Quick Start + +==== Option 1: Run with Podman (Recommended) + +[source,bash] +---- +cd social-media-polygraph +./scripts/start-dev.sh +---- + +This starts all services: - Backend API: http://localhost:8000 - +Frontend: http://localhost:3000 - API Docs: http://localhost:8000/docs + +==== Option 2: Manual Development + +*Backend:* + +[source,bash] +---- +cd backend +poetry install +cp .env.example .env +# Edit .env with your settings +poetry run python -m spacy download en_core_web_sm +poetry run python -m app.main +---- + +*Frontend:* + +[source,bash] +---- +cd frontend +npm install +cp .env.example .env +npm run dev +---- + +=== 🏗️ Architecture + +.... +┌─────────────────────────────────────────┐ +│ Web UI / API / Browser Extension │ +└────────────────┬────────────────────────┘ + │ + ┌───────▼────────┐ + │ FastAPI │ + │ Backend │ + └───────┬────────┘ + │ + ┌────────────┼────────────┐ + │ │ │ +┌───▼───┐ ┌───▼───┐ ┌───▼──────┐ +│Arango │ │ XTDB │ │Dragonfly │ +│ DB │ │(Time) │ │ (Cache) │ +└───────┘ └───────┘ └──────────┘ +.... + +=== 📝 What to Review + +==== High Priority - Core Functionality + +[arabic] +. *Backend API (`+backend/app/+`)* +* `+main.py+` - FastAPI application setup +* `+api/endpoints/claims.py+` - Claim verification endpoint +* `+ml/nlp_processor.py+` - NLP processing +* `+ml/credibility_scorer.py+` - Scoring algorithm +* `+services/claim_service.py+` - Business logic +. *Frontend (`+frontend/src/+`)* +* `+pages/VerifyPage.tsx+` - Main verification interface +* `+components/VerificationResult.tsx+` - Results display +* `+services/api.ts+` - API client +. *Infrastructure* +* `+infrastructure/podman/compose.yaml+` - Container orchestration +* `+.github/workflows/ci.yml+` - CI/CD pipeline + +==== Medium Priority - Supporting Code + +[arabic, start=4] +. *Database Clients (`+backend/app/db/+`)* +* `+arango.py+` - ArangoDB integration +* `+xtdb_client.py+` - Temporal database +* `+cache.py+` - Dragonfly cache +. *Authentication (`+backend/app/+`)* +* `+core/security.py+` - JWT & password hashing +* `+api/endpoints/auth.py+` - Auth endpoints +. *Browser Extension* +* `+browser-extension/src/content.js+` - In-page integration +* `+browser-extension/src/background.js+` - Service worker + +==== Lower Priority - Review as Needed + +[arabic, start=7] +. *Tests (`+backend/tests/+`)* +* Unit tests for NLP and scoring +* Integration tests for API +. *Documentation (`+docs/+`, README, etc.)* +* Architecture overview +* API documentation +* Deployment guide + +=== ⚠️ Important Notes + +==== What Works + +* ✅ Complete project structure +* ✅ All code is syntactically correct +* ✅ Proper error handling +* ✅ Type safety (TypeScript/Python) +* ✅ Security best practices +* ✅ Production-ready architecture + +==== What Needs Configuration + +[arabic] +. *External API Keys* (Optional but recommended) +* OpenAI/Anthropic for advanced NLP +* News API for additional sources +* Fact-checking service APIs +. *Database Setup* +* Will be initialized automatically on first run +* Default credentials in `+.env.example+` +. *NLP Models* +* spaCy model downloads on first run +* Or run: `+python -m spacy download en_core_web_sm+` + +==== What’s Mocked/Placeholder + +[arabic] +. *Fact-Checking APIs* +* Google Fact Check, Snopes, PolitiFact APIs are mocked +* Replace with real API calls when you have keys +* Located in `+backend/app/services/fact_checker.py+` +. *Browser Extension Icons* +* Manifest references icon files +* Add actual icon PNG files to `+browser-extension/public/+` + +=== 🔧 Next Steps to Make it Production-Ready + +==== Immediate (Required) + +[arabic] +. Change all default passwords and secrets in `+.env+` +. Download spaCy NLP models +. Test the basic claim verification flow + +==== Short-term (Recommended) + +[arabic] +. Add real fact-checking API integrations +. Create browser extension icons +. Set up SSL certificates for production +. Configure external API keys + +==== Medium-term (Optional) + +[arabic] +. Deploy to production server +. Set up monitoring and alerts +. Add more fact-checking sources +. Enhance ML models +. Add webhook support +. Create export functionality (PDF/CSV) + +=== 📚 Documentation + +All documentation is comprehensive and ready: + +* *README.md* - Complete overview and quick start +* *docs/API.md* - Full API documentation +* *docs/ARCHITECTURE.md* - System architecture +* *docs/DEPLOYMENT.md* - Production deployment guide +* *CONTRIBUTING.md* - Contribution guidelines + +=== 🧪 Testing + +Run tests to verify everything works: + +[source,bash] +---- +# Backend tests +cd backend +poetry install +poetry run pytest + +# Frontend type checking +cd frontend +npm install +npm run type-check +npm run lint +---- + +=== 💡 Technology Highlights + +*Why These Choices:* + +* *ArangoDB*: Multi-model database perfect for both documents and graph +relationships +* *XTDB*: Temporal queries essential for tracking claim verification +changes over time +* *Dragonfly*: Modern Redis alternative with better performance +* *FastAPI*: Modern async Python framework with auto-generated docs +* *React + TypeScript*: Type-safe, component-based UI + +=== 🎓 Learning Resources + +The codebase demonstrates: - Microservices architecture - Async/await +patterns - Type-driven development - Test-driven development - CI/CD +pipelines - Container orchestration - Graph databases - Temporal +databases - NLP/ML integration - Security best practices + +=== 🔍 Code Quality + +* Type hints throughout Python code +* Full TypeScript typing +* Comprehensive error handling +* Logging and monitoring +* Rate limiting +* Input validation +* SQL injection prevention (NoSQL) +* XSS protection +* CORS configuration +* Security headers + +=== 📊 Performance Optimizations + +* Caching with Dragonfly +* Database indexing +* Async/await throughout +* Connection pooling +* Query optimization +* Image compression (frontend) +* Code splitting potential +* CDN-ready static assets + +=== 🚨 Known Limitations + +[arabic] +. *Fact-checking APIs are mocked* - Need real API integrations +. *NLP models are basic* - Can be enhanced with custom fine-tuning +. *No real-time updates* - Could add WebSocket support +. *Single-language* - Currently English-focused +. *Limited platform coverage* - Browser extension supports major +platforms + +=== 💰 Cost Considerations + +*Free/Open Source:* - All core technology stack - Can run on free tier +VPS + +*Paid (Optional):* - Fact-checking API subscriptions - Advanced NLP +models (OpenAI/Anthropic) - Production hosting - Domain name - SSL +certificate (Let’s Encrypt is free) + +=== 🎉 What You Got + +A *complete, production-ready fact-checking platform* including: + +✅ Full-stack application ✅ AI/ML integration ✅ Multiple databases +(document, graph, temporal, cache) ✅ Browser extension ✅ CI/CD +pipeline ✅ Comprehensive tests ✅ Complete documentation ✅ Security +implementation ✅ Scalable architecture ✅ Modern tech stack + +*Estimated Development Time Saved:* 80-120 hours + +*Market Value:* $15,000 - $30,000+ if developed commercially + +*Lines of Code:* ~7,400 across 73 files + +=== 🔮 Future Enhancements + +The codebase is structured to easily add: - Real-time monitoring - +Mobile apps - Multi-language support - Advanced ML models - More social +platforms - Analytics dashboard - Admin panel - Webhook system - Export +functionality - Email notifications + +''''' + +*Enjoy exploring the codebase!* Start with the README.md for setup +instructions, then dive into the code. The architecture is clean, +well-documented, and ready for you to customize and extend. diff --git a/DEVELOPMENT_SUMMARY.md b/DEVELOPMENT_SUMMARY.md deleted file mode 100644 index 93cdffa..0000000 --- a/DEVELOPMENT_SUMMARY.md +++ /dev/null @@ -1,369 +0,0 @@ -# Development Summary - -**Generated:** Autonomous development session -**Status:** ✅ Complete -**Commits:** 2 (Initial CLAUDE.md + Full implementation) -**Files Created:** 73 -**Lines of Code:** ~7,400 - -## What Was Built - -I've created a **complete, production-ready AI-powered fact-checking platform** called Social Media Polygraph. This is a comprehensive system for verifying claims and detecting misinformation on social media. - -## 🎯 Key Features Implemented - -### Backend (Python/FastAPI) -- ✅ Full RESTful API with async FastAPI -- ✅ ArangoDB multi-model database (documents + graph) -- ✅ XTDB temporal database for claim history -- ✅ Dragonfly high-performance cache -- ✅ Advanced NLP with spaCy (entity extraction, sentiment analysis) -- ✅ Credibility scoring algorithm -- ✅ Fact-checking service integrations -- ✅ JWT authentication + API key management -- ✅ Rate limiting and security -- ✅ Comprehensive test suite - -### Frontend (React/TypeScript) -- ✅ Modern React 18 with TypeScript -- ✅ Responsive UI with TailwindCSS -- ✅ Claim verification interface -- ✅ Results visualization -- ✅ Temporal history display -- ✅ React Query for data fetching -- ✅ Full type safety - -### Browser Extension -- ✅ Chrome/Firefox compatible -- ✅ In-context verification on Twitter/X, Facebook, Instagram -- ✅ Popup interface -- ✅ Context menu integration -- ✅ Background processing - -### Infrastructure -- ✅ Podman containerization -- ✅ Multi-container orchestration -- ✅ Production deployment configs -- ✅ CI/CD with GitHub Actions -- ✅ Comprehensive documentation - -## 📊 Project Statistics - -``` -Backend: - - Python files: 23 - - Test files: 5 - - API endpoints: 8+ - - Database collections: 8 - - ML/NLP modules: 2 - -Frontend: - - React components: 7 - - Pages: 4 - - TypeScript files: 12 - - API services: 1 - -Infrastructure: - - Containerfiles: 2 - - Compose files: 1 - - CI/CD workflows: 2 - - Scripts: 2 - -Documentation: - - README: Comprehensive - - API docs: Complete - - Architecture: Detailed - - Deployment: Production-ready -``` - -## 🚀 Quick Start - -### Option 1: Run with Podman (Recommended) - -```bash -cd social-media-polygraph -./scripts/start-dev.sh -``` - -This starts all services: -- Backend API: http://localhost:8000 -- Frontend: http://localhost:3000 -- API Docs: http://localhost:8000/docs - -### Option 2: Manual Development - -**Backend:** -```bash -cd backend -poetry install -cp .env.example .env -# Edit .env with your settings -poetry run python -m spacy download en_core_web_sm -poetry run python -m app.main -``` - -**Frontend:** -```bash -cd frontend -npm install -cp .env.example .env -npm run dev -``` - -## 🏗️ Architecture - -``` -┌─────────────────────────────────────────┐ -│ Web UI / API / Browser Extension │ -└────────────────┬────────────────────────┘ - │ - ┌───────▼────────┐ - │ FastAPI │ - │ Backend │ - └───────┬────────┘ - │ - ┌────────────┼────────────┐ - │ │ │ -┌───▼───┐ ┌───▼───┐ ┌───▼──────┐ -│Arango │ │ XTDB │ │Dragonfly │ -│ DB │ │(Time) │ │ (Cache) │ -└───────┘ └───────┘ └──────────┘ -``` - -## 📝 What to Review - -### High Priority - Core Functionality - -1. **Backend API (`backend/app/`)** - - `main.py` - FastAPI application setup - - `api/endpoints/claims.py` - Claim verification endpoint - - `ml/nlp_processor.py` - NLP processing - - `ml/credibility_scorer.py` - Scoring algorithm - - `services/claim_service.py` - Business logic - -2. **Frontend (`frontend/src/`)** - - `pages/VerifyPage.tsx` - Main verification interface - - `components/VerificationResult.tsx` - Results display - - `services/api.ts` - API client - -3. **Infrastructure** - - `infrastructure/podman/compose.yaml` - Container orchestration - - `.github/workflows/ci.yml` - CI/CD pipeline - -### Medium Priority - Supporting Code - -4. **Database Clients (`backend/app/db/`)** - - `arango.py` - ArangoDB integration - - `xtdb_client.py` - Temporal database - - `cache.py` - Dragonfly cache - -5. **Authentication (`backend/app/`)** - - `core/security.py` - JWT & password hashing - - `api/endpoints/auth.py` - Auth endpoints - -6. **Browser Extension** - - `browser-extension/src/content.js` - In-page integration - - `browser-extension/src/background.js` - Service worker - -### Lower Priority - Review as Needed - -7. **Tests (`backend/tests/`)** - - Unit tests for NLP and scoring - - Integration tests for API - -8. **Documentation (`docs/`, README, etc.)** - - Architecture overview - - API documentation - - Deployment guide - -## ⚠️ Important Notes - -### What Works -- ✅ Complete project structure -- ✅ All code is syntactically correct -- ✅ Proper error handling -- ✅ Type safety (TypeScript/Python) -- ✅ Security best practices -- ✅ Production-ready architecture - -### What Needs Configuration - -1. **External API Keys** (Optional but recommended) - - OpenAI/Anthropic for advanced NLP - - News API for additional sources - - Fact-checking service APIs - -2. **Database Setup** - - Will be initialized automatically on first run - - Default credentials in `.env.example` - -3. **NLP Models** - - spaCy model downloads on first run - - Or run: `python -m spacy download en_core_web_sm` - -### What's Mocked/Placeholder - -1. **Fact-Checking APIs** - - Google Fact Check, Snopes, PolitiFact APIs are mocked - - Replace with real API calls when you have keys - - Located in `backend/app/services/fact_checker.py` - -2. **Browser Extension Icons** - - Manifest references icon files - - Add actual icon PNG files to `browser-extension/public/` - -## 🔧 Next Steps to Make it Production-Ready - -### Immediate (Required) -1. Change all default passwords and secrets in `.env` -2. Download spaCy NLP models -3. Test the basic claim verification flow - -### Short-term (Recommended) -1. Add real fact-checking API integrations -2. Create browser extension icons -3. Set up SSL certificates for production -4. Configure external API keys - -### Medium-term (Optional) -1. Deploy to production server -2. Set up monitoring and alerts -3. Add more fact-checking sources -4. Enhance ML models -5. Add webhook support -6. Create export functionality (PDF/CSV) - -## 📚 Documentation - -All documentation is comprehensive and ready: - -- **README.md** - Complete overview and quick start -- **docs/API.md** - Full API documentation -- **docs/ARCHITECTURE.md** - System architecture -- **docs/DEPLOYMENT.md** - Production deployment guide -- **CONTRIBUTING.md** - Contribution guidelines - -## 🧪 Testing - -Run tests to verify everything works: - -```bash -# Backend tests -cd backend -poetry install -poetry run pytest - -# Frontend type checking -cd frontend -npm install -npm run type-check -npm run lint -``` - -## 💡 Technology Highlights - -**Why These Choices:** - -- **ArangoDB**: Multi-model database perfect for both documents and graph relationships -- **XTDB**: Temporal queries essential for tracking claim verification changes over time -- **Dragonfly**: Modern Redis alternative with better performance -- **FastAPI**: Modern async Python framework with auto-generated docs -- **React + TypeScript**: Type-safe, component-based UI - -## 🎓 Learning Resources - -The codebase demonstrates: -- Microservices architecture -- Async/await patterns -- Type-driven development -- Test-driven development -- CI/CD pipelines -- Container orchestration -- Graph databases -- Temporal databases -- NLP/ML integration -- Security best practices - -## 🔍 Code Quality - -- Type hints throughout Python code -- Full TypeScript typing -- Comprehensive error handling -- Logging and monitoring -- Rate limiting -- Input validation -- SQL injection prevention (NoSQL) -- XSS protection -- CORS configuration -- Security headers - -## 📊 Performance Optimizations - -- Caching with Dragonfly -- Database indexing -- Async/await throughout -- Connection pooling -- Query optimization -- Image compression (frontend) -- Code splitting potential -- CDN-ready static assets - -## 🚨 Known Limitations - -1. **Fact-checking APIs are mocked** - Need real API integrations -2. **NLP models are basic** - Can be enhanced with custom fine-tuning -3. **No real-time updates** - Could add WebSocket support -4. **Single-language** - Currently English-focused -5. **Limited platform coverage** - Browser extension supports major platforms - -## 💰 Cost Considerations - -**Free/Open Source:** -- All core technology stack -- Can run on free tier VPS - -**Paid (Optional):** -- Fact-checking API subscriptions -- Advanced NLP models (OpenAI/Anthropic) -- Production hosting -- Domain name -- SSL certificate (Let's Encrypt is free) - -## 🎉 What You Got - -A **complete, production-ready fact-checking platform** including: - -✅ Full-stack application -✅ AI/ML integration -✅ Multiple databases (document, graph, temporal, cache) -✅ Browser extension -✅ CI/CD pipeline -✅ Comprehensive tests -✅ Complete documentation -✅ Security implementation -✅ Scalable architecture -✅ Modern tech stack - -**Estimated Development Time Saved:** 80-120 hours - -**Market Value:** $15,000 - $30,000+ if developed commercially - -**Lines of Code:** ~7,400 across 73 files - -## 🔮 Future Enhancements - -The codebase is structured to easily add: -- Real-time monitoring -- Mobile apps -- Multi-language support -- Advanced ML models -- More social platforms -- Analytics dashboard -- Admin panel -- Webhook system -- Export functionality -- Email notifications - ---- - -**Enjoy exploring the codebase!** Start with the README.md for setup instructions, then dive into the code. The architecture is clean, well-documented, and ready for you to customize and extend. diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc new file mode 100644 index 0000000..c16c188 --- /dev/null +++ b/MAINTAINERS.adoc @@ -0,0 +1,214 @@ +== Maintainers + +This document lists the maintainers of the Social Media Polygraph +project and defines the governance structure. + +=== Current Maintainers + +==== Lead Maintainers + +* *[Your Name]* (@yourusername) +** *Role*: Project Lead, Architecture +** *Focus*: Overall vision, architecture decisions, major releases +** *Timezone*: UTC-8 +** *Contact*: lead@yourdomain.com + +==== Core Maintainers + +==== Component Maintainers + +===== Backend (Python/FastAPI) + +* *[Maintainer Name]* (@username) - API & Services +* *[Maintainer Name]* (@username) - ML/NLP Pipeline +* *[Maintainer Name]* (@username) - Database Integration + +===== Frontend (React/TypeScript) + +* *[Maintainer Name]* (@username) - UI Components +* *[Maintainer Name]* (@username) - State Management + +===== Infrastructure + +* *[Maintainer Name]* (@username) - CI/CD & Deployment +* *[Maintainer Name]* (@username) - Container Orchestration + +===== Browser Extension + +* *[Maintainer Name]* (@username) - Extension Development + +=== Governance Model + +==== Tri-Perimeter Contribution Framework (TPCF) + +This project uses a *graduated trust model* with three perimeters: + +===== Perimeter 1: Core (Maintainers Only) + +*Access Level*: Write access to main/production branches + +*Responsibilities*: - Review and merge pull requests - Make +architectural decisions - Manage releases and versioning - Security +vulnerability response - Community moderation + +*Requirements*: - 6+ months of active contribution - Deep understanding +of codebase - Demonstrated judgment and responsibility - Unanimous +approval from existing core maintainers + +*Current Members*: Listed above as Lead/Core Maintainers + +===== Perimeter 2: Trusted Contributors + +*Access Level*: Write access to development branches, auto-approved +CI/CD + +*Responsibilities*: - Major feature development - Significant +refactoring - Documentation improvements - Mentoring new contributors + +*Requirements*: - 3+ months of active contribution - 10+ merged pull +requests - Demonstrated code quality and testing practices - Approval +from 2+ core maintainers + +*Current Members*: (To be populated as project grows) + +===== Perimeter 3: Community Sandbox + +*Access Level*: Fork-based contributions, public issues/discussions + +*Responsibilities*: - Bug reports and feature requests - Pull requests +(require review) - Documentation fixes - Community support + +*Requirements*: None - open to all + +*Process*: 1. Fork repository 2. Make changes in your fork 3. Submit +pull request 4. Address review feedback 5. Maintainer merges when +approved + +=== Decision Making + +==== Consensus-Based + +* *Small changes*: Any maintainer can merge after review +* *Medium changes*: Requires approval from component maintainer +* *Large changes*: Requires approval from 2+ core maintainers +* *Breaking changes*: Requires approval from lead maintainer + 2+ core +* *Governance changes*: Requires unanimous approval from all core +maintainers + +==== Conflict Resolution + +[arabic] +. *Discussion*: Try to reach consensus through discussion +. *Mediation*: Lead maintainer mediates if needed +. *Vote*: Core maintainers vote (simple majority) +. *Final Decision*: Lead maintainer has final say in deadlocks + +=== Maintainer Responsibilities + +==== Code Review + +* Respond to PRs within 3 business days +* Provide constructive, actionable feedback +* Test changes locally when needed +* Ensure CI/CD passes before merging + +==== Security + +* Respond to security reports within 48 hours +* Coordinate security fixes and disclosures +* Monitor dependency vulnerabilities +* Keep security policy up to date + +==== Community + +* Welcome new contributors +* Answer questions in issues/discussions +* Enforce Code of Conduct fairly +* Recognize and appreciate contributions + +==== Release Management + +* Follow semantic versioning (SemVer) +* Maintain CHANGELOG.md +* Test releases thoroughly +* Coordinate with dependent projects + +==== Documentation + +* Keep README and guides up to date +* Document breaking changes clearly +* Maintain API documentation +* Write migration guides when needed + +=== Becoming a Maintainer + +==== Path to Trusted Contributor (Perimeter 2) + +[arabic] +. *Contribute regularly* for 3+ months +. *Submit quality PRs*: Well-tested, documented, follows guidelines +. *Engage with community*: Help others, review PRs, participate in +discussions +. *Request nomination*: Ask an existing maintainer or self-nominate +. *Review period*: Core maintainers review contributions +. *Approval*: 2+ core maintainers approve +. *Onboarding*: Access granted, added to this document + +==== Path to Core Maintainer (Perimeter 1) + +[arabic] +. *Serve as Trusted Contributor* for 6+ months +. *Deep expertise*: Demonstrate mastery of component/area +. *Leadership*: Mentor others, drive initiatives +. *Request nomination*: Self-nominate or be nominated +. *Review period*: All core maintainers review +. *Approval*: Unanimous approval required +. *Onboarding*: Write access, voting rights, added to this document + +=== Emeritus Status + +Maintainers who step down remain listed as *Emeritus Maintainers*: + +==== Emeritus Maintainers + +*Rights*: - Honorary recognition - Advisory role (non-binding) - Can +return to active status if desired + +*Process to Return*: 1. Notify current core maintainers 2. Review recent +changes 3. 1-month trial period 4. Core maintainers approve return + +=== Maintainer Expectations + +==== Time Commitment + +* *Core Maintainers*: 5-10 hours/week +* *Component Maintainers*: 3-5 hours/week +* *Emeritus*: No commitment + +==== Availability + +* Respond to critical issues within 24 hours +* Participate in monthly maintainer calls (when established) +* Give notice for extended absences (2+ weeks) + +==== Professional Conduct + +* Follow Code of Conduct +* Maintain confidentiality of security issues +* Disclose conflicts of interest +* Represent project professionally + +=== Contact + +* *General Maintainer Contact*: maintainers@yourdomain.com +* *Security Issues*: security@yourdomain.com (see SECURITY.md) +* *Code of Conduct Issues*: conduct@yourdomain.com (see +CODE_OF_CONDUCT.md) + +=== Changes to This Document + +This document is versioned and changes require: - Pull request with +clear rationale - Approval from all core maintainers - 7-day comment +period for community feedback + +*Version*: 1.0 *Last Updated*: 2024-01-15 *Next Review*: 2024-07-15 diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index a88580a..0000000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,230 +0,0 @@ -# Maintainers - -This document lists the maintainers of the Social Media Polygraph project and defines the governance structure. - -## Current Maintainers - -### Lead Maintainers - -- **[Your Name]** (@yourusername) - - **Role**: Project Lead, Architecture - - **Focus**: Overall vision, architecture decisions, major releases - - **Timezone**: UTC-8 - - **Contact**: lead@yourdomain.com - -### Core Maintainers - - - -### Component Maintainers - -#### Backend (Python/FastAPI) -- **[Maintainer Name]** (@username) - API & Services -- **[Maintainer Name]** (@username) - ML/NLP Pipeline -- **[Maintainer Name]** (@username) - Database Integration - -#### Frontend (React/TypeScript) -- **[Maintainer Name]** (@username) - UI Components -- **[Maintainer Name]** (@username) - State Management - -#### Infrastructure -- **[Maintainer Name]** (@username) - CI/CD & Deployment -- **[Maintainer Name]** (@username) - Container Orchestration - -#### Browser Extension -- **[Maintainer Name]** (@username) - Extension Development - -## Governance Model - -### Tri-Perimeter Contribution Framework (TPCF) - -This project uses a **graduated trust model** with three perimeters: - -#### Perimeter 1: Core (Maintainers Only) - -**Access Level**: Write access to main/production branches - -**Responsibilities**: -- Review and merge pull requests -- Make architectural decisions -- Manage releases and versioning -- Security vulnerability response -- Community moderation - -**Requirements**: -- 6+ months of active contribution -- Deep understanding of codebase -- Demonstrated judgment and responsibility -- Unanimous approval from existing core maintainers - -**Current Members**: Listed above as Lead/Core Maintainers - -#### Perimeter 2: Trusted Contributors - -**Access Level**: Write access to development branches, auto-approved CI/CD - -**Responsibilities**: -- Major feature development -- Significant refactoring -- Documentation improvements -- Mentoring new contributors - -**Requirements**: -- 3+ months of active contribution -- 10+ merged pull requests -- Demonstrated code quality and testing practices -- Approval from 2+ core maintainers - -**Current Members**: (To be populated as project grows) - -#### Perimeter 3: Community Sandbox - -**Access Level**: Fork-based contributions, public issues/discussions - -**Responsibilities**: -- Bug reports and feature requests -- Pull requests (require review) -- Documentation fixes -- Community support - -**Requirements**: None - open to all - -**Process**: -1. Fork repository -2. Make changes in your fork -3. Submit pull request -4. Address review feedback -5. Maintainer merges when approved - -## Decision Making - -### Consensus-Based - -- **Small changes**: Any maintainer can merge after review -- **Medium changes**: Requires approval from component maintainer -- **Large changes**: Requires approval from 2+ core maintainers -- **Breaking changes**: Requires approval from lead maintainer + 2+ core -- **Governance changes**: Requires unanimous approval from all core maintainers - -### Conflict Resolution - -1. **Discussion**: Try to reach consensus through discussion -2. **Mediation**: Lead maintainer mediates if needed -3. **Vote**: Core maintainers vote (simple majority) -4. **Final Decision**: Lead maintainer has final say in deadlocks - -## Maintainer Responsibilities - -### Code Review - -- Respond to PRs within 3 business days -- Provide constructive, actionable feedback -- Test changes locally when needed -- Ensure CI/CD passes before merging - -### Security - -- Respond to security reports within 48 hours -- Coordinate security fixes and disclosures -- Monitor dependency vulnerabilities -- Keep security policy up to date - -### Community - -- Welcome new contributors -- Answer questions in issues/discussions -- Enforce Code of Conduct fairly -- Recognize and appreciate contributions - -### Release Management - -- Follow semantic versioning (SemVer) -- Maintain CHANGELOG.md -- Test releases thoroughly -- Coordinate with dependent projects - -### Documentation - -- Keep README and guides up to date -- Document breaking changes clearly -- Maintain API documentation -- Write migration guides when needed - -## Becoming a Maintainer - -### Path to Trusted Contributor (Perimeter 2) - -1. **Contribute regularly** for 3+ months -2. **Submit quality PRs**: Well-tested, documented, follows guidelines -3. **Engage with community**: Help others, review PRs, participate in discussions -4. **Request nomination**: Ask an existing maintainer or self-nominate -5. **Review period**: Core maintainers review contributions -6. **Approval**: 2+ core maintainers approve -7. **Onboarding**: Access granted, added to this document - -### Path to Core Maintainer (Perimeter 1) - -1. **Serve as Trusted Contributor** for 6+ months -2. **Deep expertise**: Demonstrate mastery of component/area -3. **Leadership**: Mentor others, drive initiatives -4. **Request nomination**: Self-nominate or be nominated -5. **Review period**: All core maintainers review -6. **Approval**: Unanimous approval required -7. **Onboarding**: Write access, voting rights, added to this document - -## Emeritus Status - -Maintainers who step down remain listed as **Emeritus Maintainers**: - -### Emeritus Maintainers - - - -**Rights**: -- Honorary recognition -- Advisory role (non-binding) -- Can return to active status if desired - -**Process to Return**: -1. Notify current core maintainers -2. Review recent changes -3. 1-month trial period -4. Core maintainers approve return - -## Maintainer Expectations - -### Time Commitment - -- **Core Maintainers**: 5-10 hours/week -- **Component Maintainers**: 3-5 hours/week -- **Emeritus**: No commitment - -### Availability - -- Respond to critical issues within 24 hours -- Participate in monthly maintainer calls (when established) -- Give notice for extended absences (2+ weeks) - -### Professional Conduct - -- Follow Code of Conduct -- Maintain confidentiality of security issues -- Disclose conflicts of interest -- Represent project professionally - -## Contact - -- **General Maintainer Contact**: maintainers@yourdomain.com -- **Security Issues**: security@yourdomain.com (see SECURITY.md) -- **Code of Conduct Issues**: conduct@yourdomain.com (see CODE_OF_CONDUCT.md) - -## Changes to This Document - -This document is versioned and changes require: -- Pull request with clear rationale -- Approval from all core maintainers -- 7-day comment period for community feedback - -**Version**: 1.0 -**Last Updated**: 2024-01-15 -**Next Review**: 2024-07-15 diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..2ab5cc6 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,454 @@ +== Security Policy + +We take security seriously. We appreciate your efforts to responsibly +disclose vulnerabilities and will make every effort to acknowledge your +contributions. + +=== Table of Contents + +* link:#reporting-a-vulnerability[Reporting a Vulnerability] +* link:#what-to-include[What to Include] +* link:#response-timeline[Response Timeline] +* link:#disclosure-policy[Disclosure Policy] +* link:#scope[Scope] +* link:#safe-harbour[Safe Harbour] +* link:#recognition[Recognition] +* link:#security-updates[Security Updates] +* link:#security-best-practices[Security Best Practices] + +''''' + +=== Reporting a Vulnerability + +==== Preferred Method: GitHub Security Advisories + +The preferred method for reporting security vulnerabilities is through +GitHub’s Security Advisory feature: + +[arabic] +. Navigate to +https://github.com/hyperpolymath/social-media-polygraph/security/advisories/new[Report +a Vulnerability] +. Click *"`Report a vulnerability`"* +. Complete the form with as much detail as possible +. Submit — we’ll receive a private notification + +This method ensures: + +* End-to-end encryption of your report +* Private discussion space for collaboration +* Coordinated disclosure tooling +* Automatic credit when the advisory is published + +==== Alternative: Encrypted Email + +If you cannot use GitHub Security Advisories, you may email us directly: + +[width="100%",cols="50%,50%",] +|=== +|*Email* |j.d.a.jewell@open.ac.uk +|*PGP Key* |https://github.com/hyperpolymath.gpg[Download Public Key] +|*Fingerprint* |`+TBD+` +|=== + +[source,bash] +---- +# Import our PGP key +curl -sSL https://github.com/hyperpolymath.gpg | gpg --import + +# Verify fingerprint +gpg --fingerprint j.d.a.jewell@open.ac.uk + +# Encrypt your report +gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt +---- + +____ +*⚠️ Important:* Do not report security vulnerabilities through public +GitHub issues, pull requests, discussions, or social media. +____ + +''''' + +=== What to Include + +A good vulnerability report helps us understand and reproduce the issue +quickly. + +==== Required Information + +* *Description*: Clear explanation of the vulnerability +* *Impact*: What an attacker could achieve (confidentiality, integrity, +availability) +* *Affected versions*: Which versions/commits are affected +* *Reproduction steps*: Detailed steps to reproduce the issue + +==== Helpful Additional Information + +* *Proof of concept*: Code, scripts, or screenshots demonstrating the +vulnerability +* *Attack scenario*: Realistic attack scenario showing exploitability +* *CVSS score*: Your assessment of severity (use +https://www.first.org/cvss/calculator/3.1[CVSS 3.1 Calculator]) +* *CWE ID*: Common Weakness Enumeration identifier if known +* *Suggested fix*: If you have ideas for remediation +* *References*: Links to related vulnerabilities, research, or +advisories + +==== Example Report Structure + +[source,markdown] +---- +## Summary +[One-sentence description of the vulnerability] + +## Vulnerability Type +[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] + +## Affected Component +[File path, function name, API endpoint, etc.] + +## Affected Versions +[Version range or specific commits] + +## Severity Assessment +- CVSS 3.1 Score: [X.X] +- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] + +## Description +[Detailed technical description] + +## Steps to Reproduce +1. [First step] +2. [Second step] +3. [...] + +## Proof of Concept +[Code, curl commands, screenshots, etc.] + +## Impact +[What can an attacker achieve?] + +## Suggested Remediation +[Optional: your ideas for fixing] + +## References +[Links to related issues, CVEs, research] +---- + +''''' + +=== Response Timeline + +We commit to the following response times: + +[width="100%",cols="24%,35%,41%",options="header",] +|=== +|Stage |Timeframe |Description +|*Initial Response* |48 hours |We acknowledge receipt and confirm we’re +investigating + +|*Triage* |7 days |We assess severity, confirm the vulnerability, and +estimate timeline + +|*Status Update* |Every 7 days |Regular updates on remediation progress + +|*Resolution* |90 days |Target for fix development and release (complex +issues may take longer) + +|*Disclosure* |90 days |Public disclosure after fix is available +(coordinated with you) +|=== + +____ +*Note:* These are targets, not guarantees. Complex vulnerabilities may +require more time. We’ll communicate openly about any delays. +____ + +''''' + +=== Disclosure Policy + +We follow *coordinated disclosure* (also known as responsible +disclosure): + +[arabic] +. *You report* the vulnerability privately +. *We acknowledge* and begin investigation +. *We develop* a fix and prepare a release +. *We coordinate* disclosure timing with you +. *We publish* security advisory and fix simultaneously +. *You may publish* your research after disclosure + +==== Our Commitments + +* We will not take legal action against researchers who follow this +policy +* We will work with you to understand and resolve the issue +* We will credit you in the security advisory (unless you prefer +anonymity) +* We will notify you before public disclosure +* We will publish advisories with sufficient detail for users to assess +risk + +==== Your Commitments + +* Report vulnerabilities promptly after discovery +* Give us reasonable time to address the issue before disclosure +* Do not access, modify, or delete data beyond what’s necessary to +demonstrate the vulnerability +* Do not degrade service availability (no DoS testing on production) +* Do not share vulnerability details with others until coordinated +disclosure + +==== Disclosure Timeline + +.... +Day 0 You report vulnerability +Day 1-2 We acknowledge receipt +Day 7 We confirm vulnerability and share initial assessment +Day 7-90 We develop and test fix +Day 90 Coordinated public disclosure + (earlier if fix is ready; later by mutual agreement) +.... + +If we cannot reach agreement on disclosure timing, we default to 90 days +from your initial report. + +''''' + +=== Scope + +==== In Scope ✅ + +The following are within scope for security research: + +* This repository (`+hyperpolymath/social-media-polygraph+`) and all its +code +* Official releases and packages published from this repository +* Documentation that could lead to security issues +* Build and deployment configurations in this repository +* Dependencies (report here, we’ll coordinate with upstream) + +==== Out of Scope ❌ + +The following are *not* in scope: + +* Third-party services we integrate with (report directly to them) +* Social engineering attacks against maintainers +* Physical security +* Denial of service attacks against production infrastructure +* Spam, phishing, or other non-technical attacks +* Issues already reported or publicly known +* Theoretical vulnerabilities without proof of concept + +==== Qualifying Vulnerabilities + +We’re particularly interested in: + +* Remote code execution +* SQL injection, command injection, code injection +* Authentication/authorisation bypass +* Cross-site scripting (XSS) and cross-site request forgery (CSRF) +* Server-side request forgery (SSRF) +* Path traversal / local file inclusion +* Information disclosure (credentials, PII, secrets) +* Cryptographic weaknesses +* Deserialisation vulnerabilities +* Memory safety issues (buffer overflows, use-after-free, etc.) +* Supply chain vulnerabilities (dependency confusion, etc.) +* Significant logic flaws + +==== Non-Qualifying Issues + +The following generally do not qualify as security vulnerabilities: + +* Missing security headers on non-sensitive pages +* Clickjacking on pages without sensitive actions +* Self-XSS (requires victim to paste code) +* Missing rate limiting (unless it enables a specific attack) +* Username/email enumeration (unless high-risk context) +* Missing cookie flags on non-sensitive cookies +* Software version disclosure +* Verbose error messages (unless exposing secrets) +* Best practice deviations without demonstrable impact + +''''' + +=== Safe Harbour + +We support security research conducted in good faith. + +==== Our Promise + +If you conduct security research in accordance with this policy: + +* ✅ We will not initiate legal action against you +* ✅ We will not report your activity to law enforcement +* ✅ We will work with you in good faith to resolve issues +* ✅ We consider your research authorised under the Computer Fraud and +Abuse Act (CFAA), UK Computer Misuse Act, and similar laws +* ✅ We waive any potential claim against you for circumvention of +security controls + +==== Good Faith Requirements + +To qualify for safe harbour, you must: + +* Comply with this security policy +* Report vulnerabilities promptly +* Avoid privacy violations (do not access others’ data) +* Avoid service degradation (no destructive testing) +* Not exploit vulnerabilities beyond proof-of-concept +* Not use vulnerabilities for profit (beyond bug bounties where offered) + +____ +*⚠️ Important:* This safe harbour does not extend to third-party +systems. Always check their policies before testing. +____ + +''''' + +=== Recognition + +We believe in recognising security researchers who help us improve. + +==== Hall of Fame + +Researchers who report valid vulnerabilities will be acknowledged in our +link:SECURITY-ACKNOWLEDGMENTS.md[Security Acknowledgments] (unless they +prefer anonymity). + +Recognition includes: + +* Your name (or chosen alias) +* Link to your website/profile (optional) +* Brief description of the vulnerability class +* Date of report + +==== What We Offer + +* ✅ Public credit in security advisories +* ✅ Acknowledgment in release notes +* ✅ Entry in our Hall of Fame +* ✅ Reference/recommendation letter upon request (for significant +findings) + +==== What We Don’t Currently Offer + +* ❌ Monetary bug bounties +* ❌ Hardware or swag +* ❌ Paid security research contracts + +____ +*Note:* We’re a community project with limited resources. Your +contributions help everyone who uses this software. +____ + +''''' + +=== Security Updates + +==== Receiving Updates + +To stay informed about security updates: + +* *Watch this repository*: Click "`Watch`" → "`Custom`" → Select +"`Security alerts`" +* *GitHub Security Advisories*: Published at +https://github.com/hyperpolymath/social-media-polygraph/security/advisories[Security +Advisories] +* *Release notes*: Security fixes noted in link:CHANGELOG.md[CHANGELOG] + +==== Update Policy + +[cols=",",options="header",] +|=== +|Severity |Response +|*Critical/High* |Patch release as soon as fix is ready +|*Medium* |Included in next scheduled release (or earlier) +|*Low* |Included in next scheduled release +|=== + +==== Supported Versions + +[cols=",,",options="header",] +|=== +|Version |Supported |Notes +|`+main+` branch |✅ Yes |Latest development +|Latest release |✅ Yes |Current stable +|Previous minor release |✅ Yes |Security fixes backported +|Older versions |❌ No |Please upgrade +|=== + +''''' + +=== Security Best Practices + +When using Social Media Polygraph, we recommend: + +==== General + +* Keep dependencies up to date +* Use the latest stable release +* Subscribe to security notifications +* Review configuration against security documentation +* Follow principle of least privilege + +==== For Contributors + +* Never commit secrets, credentials, or API keys +* Use signed commits (`+git config commit.gpgsign true+`) +* Review dependencies before adding them +* Run security linters locally before pushing +* Report any concerns about existing code + +''''' + +=== Additional Resources + +* https://github.com/hyperpolymath.gpg[Our PGP Public Key] +* https://github.com/hyperpolymath/social-media-polygraph/security/advisories[Security +Advisories] +* link:CHANGELOG.md[Changelog] +* link:CONTRIBUTING.md[Contributing Guidelines] +* https://cve.mitre.org/[CVE Database] +* https://www.first.org/cvss/calculator/3.1[CVSS Calculator] + +''''' + +=== Contact + +[width="100%",cols="50%,50%",options="header",] +|=== +|Purpose |Contact +|*Security issues* +|https://github.com/hyperpolymath/social-media-polygraph/security/advisories/new[Report +via GitHub] or j.d.a.jewell@open.ac.uk + +|*General questions* +|https://github.com/hyperpolymath/social-media-polygraph/discussions[GitHub +Discussions] + +|*Other enquiries* |See link:README.md[README] for contact information +|=== + +''''' + +=== Policy Changes + +This security policy may be updated from time to time. Significant +changes will be: + +* Committed to this repository with a clear commit message +* Noted in the changelog +* Announced via GitHub Discussions (for major changes) + +''''' + +_Thank you for helping keep Social Media Polygraph and its users safe._ +🛡️ + +''''' + +Last updated: 2026 · Policy version: 1.0.0 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 5689aa1..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,388 +0,0 @@ -# Security Policy - -We take security seriously. We appreciate your efforts to responsibly disclose vulnerabilities and will make every effort to acknowledge your contributions. - -## Table of Contents - -- [Reporting a Vulnerability](#reporting-a-vulnerability) -- [What to Include](#what-to-include) -- [Response Timeline](#response-timeline) -- [Disclosure Policy](#disclosure-policy) -- [Scope](#scope) -- [Safe Harbour](#safe-harbour) -- [Recognition](#recognition) -- [Security Updates](#security-updates) -- [Security Best Practices](#security-best-practices) - ---- - -## Reporting a Vulnerability - -### Preferred Method: GitHub Security Advisories - -The preferred method for reporting security vulnerabilities is through GitHub's Security Advisory feature: - -1. Navigate to [Report a Vulnerability](https://github.com/hyperpolymath/social-media-polygraph/security/advisories/new) -2. Click **"Report a vulnerability"** -3. Complete the form with as much detail as possible -4. Submit — we'll receive a private notification - -This method ensures: - -- End-to-end encryption of your report -- Private discussion space for collaboration -- Coordinated disclosure tooling -- Automatic credit when the advisory is published - -### Alternative: Encrypted Email - -If you cannot use GitHub Security Advisories, you may email us directly: - -| | | -|---|---| -| **Email** | j.d.a.jewell@open.ac.uk | -| **PGP Key** | [Download Public Key](https://github.com/hyperpolymath.gpg) | -| **Fingerprint** | `TBD` | - -```bash -# Import our PGP key -curl -sSL https://github.com/hyperpolymath.gpg | gpg --import - -# Verify fingerprint -gpg --fingerprint j.d.a.jewell@open.ac.uk - -# Encrypt your report -gpg --armor --encrypt --recipient j.d.a.jewell@open.ac.uk report.txt -``` - -> **⚠️ Important:** Do not report security vulnerabilities through public GitHub issues, pull requests, discussions, or social media. - ---- - -## What to Include - -A good vulnerability report helps us understand and reproduce the issue quickly. - -### Required Information - -- **Description**: Clear explanation of the vulnerability -- **Impact**: What an attacker could achieve (confidentiality, integrity, availability) -- **Affected versions**: Which versions/commits are affected -- **Reproduction steps**: Detailed steps to reproduce the issue - -### Helpful Additional Information - -- **Proof of concept**: Code, scripts, or screenshots demonstrating the vulnerability -- **Attack scenario**: Realistic attack scenario showing exploitability -- **CVSS score**: Your assessment of severity (use [CVSS 3.1 Calculator](https://www.first.org/cvss/calculator/3.1)) -- **CWE ID**: Common Weakness Enumeration identifier if known -- **Suggested fix**: If you have ideas for remediation -- **References**: Links to related vulnerabilities, research, or advisories - -### Example Report Structure - -```markdown -## Summary -[One-sentence description of the vulnerability] - -## Vulnerability Type -[e.g., SQL Injection, XSS, SSRF, Path Traversal, etc.] - -## Affected Component -[File path, function name, API endpoint, etc.] - -## Affected Versions -[Version range or specific commits] - -## Severity Assessment -- CVSS 3.1 Score: [X.X] -- CVSS Vector: [CVSS:3.1/AV:X/AC:X/PR:X/UI:X/S:X/C:X/I:X/A:X] - -## Description -[Detailed technical description] - -## Steps to Reproduce -1. [First step] -2. [Second step] -3. [...] - -## Proof of Concept -[Code, curl commands, screenshots, etc.] - -## Impact -[What can an attacker achieve?] - -## Suggested Remediation -[Optional: your ideas for fixing] - -## References -[Links to related issues, CVEs, research] -``` - ---- - -## Response Timeline - -We commit to the following response times: - -| Stage | Timeframe | Description | -|-------|-----------|-------------| -| **Initial Response** | 48 hours | We acknowledge receipt and confirm we're investigating | -| **Triage** | 7 days | We assess severity, confirm the vulnerability, and estimate timeline | -| **Status Update** | Every 7 days | Regular updates on remediation progress | -| **Resolution** | 90 days | Target for fix development and release (complex issues may take longer) | -| **Disclosure** | 90 days | Public disclosure after fix is available (coordinated with you) | - -> **Note:** These are targets, not guarantees. Complex vulnerabilities may require more time. We'll communicate openly about any delays. - ---- - -## Disclosure Policy - -We follow **coordinated disclosure** (also known as responsible disclosure): - -1. **You report** the vulnerability privately -2. **We acknowledge** and begin investigation -3. **We develop** a fix and prepare a release -4. **We coordinate** disclosure timing with you -5. **We publish** security advisory and fix simultaneously -6. **You may publish** your research after disclosure - -### Our Commitments - -- We will not take legal action against researchers who follow this policy -- We will work with you to understand and resolve the issue -- We will credit you in the security advisory (unless you prefer anonymity) -- We will notify you before public disclosure -- We will publish advisories with sufficient detail for users to assess risk - -### Your Commitments - -- Report vulnerabilities promptly after discovery -- Give us reasonable time to address the issue before disclosure -- Do not access, modify, or delete data beyond what's necessary to demonstrate the vulnerability -- Do not degrade service availability (no DoS testing on production) -- Do not share vulnerability details with others until coordinated disclosure - -### Disclosure Timeline - -``` -Day 0 You report vulnerability -Day 1-2 We acknowledge receipt -Day 7 We confirm vulnerability and share initial assessment -Day 7-90 We develop and test fix -Day 90 Coordinated public disclosure - (earlier if fix is ready; later by mutual agreement) -``` - -If we cannot reach agreement on disclosure timing, we default to 90 days from your initial report. - ---- - -## Scope - -### In Scope ✅ - -The following are within scope for security research: - -- This repository (`hyperpolymath/social-media-polygraph`) and all its code -- Official releases and packages published from this repository -- Documentation that could lead to security issues -- Build and deployment configurations in this repository -- Dependencies (report here, we'll coordinate with upstream) - -### Out of Scope ❌ - -The following are **not** in scope: - -- Third-party services we integrate with (report directly to them) -- Social engineering attacks against maintainers -- Physical security -- Denial of service attacks against production infrastructure -- Spam, phishing, or other non-technical attacks -- Issues already reported or publicly known -- Theoretical vulnerabilities without proof of concept - -### Qualifying Vulnerabilities - -We're particularly interested in: - -- Remote code execution -- SQL injection, command injection, code injection -- Authentication/authorisation bypass -- Cross-site scripting (XSS) and cross-site request forgery (CSRF) -- Server-side request forgery (SSRF) -- Path traversal / local file inclusion -- Information disclosure (credentials, PII, secrets) -- Cryptographic weaknesses -- Deserialisation vulnerabilities -- Memory safety issues (buffer overflows, use-after-free, etc.) -- Supply chain vulnerabilities (dependency confusion, etc.) -- Significant logic flaws - -### Non-Qualifying Issues - -The following generally do not qualify as security vulnerabilities: - -- Missing security headers on non-sensitive pages -- Clickjacking on pages without sensitive actions -- Self-XSS (requires victim to paste code) -- Missing rate limiting (unless it enables a specific attack) -- Username/email enumeration (unless high-risk context) -- Missing cookie flags on non-sensitive cookies -- Software version disclosure -- Verbose error messages (unless exposing secrets) -- Best practice deviations without demonstrable impact - ---- - -## Safe Harbour - -We support security research conducted in good faith. - -### Our Promise - -If you conduct security research in accordance with this policy: - -- ✅ We will not initiate legal action against you -- ✅ We will not report your activity to law enforcement -- ✅ We will work with you in good faith to resolve issues -- ✅ We consider your research authorised under the Computer Fraud and Abuse Act (CFAA), UK Computer Misuse Act, and similar laws -- ✅ We waive any potential claim against you for circumvention of security controls - -### Good Faith Requirements - -To qualify for safe harbour, you must: - -- Comply with this security policy -- Report vulnerabilities promptly -- Avoid privacy violations (do not access others' data) -- Avoid service degradation (no destructive testing) -- Not exploit vulnerabilities beyond proof-of-concept -- Not use vulnerabilities for profit (beyond bug bounties where offered) - -> **⚠️ Important:** This safe harbour does not extend to third-party systems. Always check their policies before testing. - ---- - -## Recognition - -We believe in recognising security researchers who help us improve. - -### Hall of Fame - -Researchers who report valid vulnerabilities will be acknowledged in our [Security Acknowledgments](SECURITY-ACKNOWLEDGMENTS.md) (unless they prefer anonymity). - -Recognition includes: - -- Your name (or chosen alias) -- Link to your website/profile (optional) -- Brief description of the vulnerability class -- Date of report - -### What We Offer - -- ✅ Public credit in security advisories -- ✅ Acknowledgment in release notes -- ✅ Entry in our Hall of Fame -- ✅ Reference/recommendation letter upon request (for significant findings) - -### What We Don't Currently Offer - -- ❌ Monetary bug bounties -- ❌ Hardware or swag -- ❌ Paid security research contracts - -> **Note:** We're a community project with limited resources. Your contributions help everyone who uses this software. - ---- - -## Security Updates - -### Receiving Updates - -To stay informed about security updates: - -- **Watch this repository**: Click "Watch" → "Custom" → Select "Security alerts" -- **GitHub Security Advisories**: Published at [Security Advisories](https://github.com/hyperpolymath/social-media-polygraph/security/advisories) -- **Release notes**: Security fixes noted in [CHANGELOG](CHANGELOG.md) - -### Update Policy - -| Severity | Response | -|----------|----------| -| **Critical/High** | Patch release as soon as fix is ready | -| **Medium** | Included in next scheduled release (or earlier) | -| **Low** | Included in next scheduled release | - -### Supported Versions - - - -| Version | Supported | Notes | -|---------|-----------|-------| -| `main` branch | ✅ Yes | Latest development | -| Latest release | ✅ Yes | Current stable | -| Previous minor release | ✅ Yes | Security fixes backported | -| Older versions | ❌ No | Please upgrade | - ---- - -## Security Best Practices - -When using Social Media Polygraph, we recommend: - -### General - -- Keep dependencies up to date -- Use the latest stable release -- Subscribe to security notifications -- Review configuration against security documentation -- Follow principle of least privilege - -### For Contributors - -- Never commit secrets, credentials, or API keys -- Use signed commits (`git config commit.gpgsign true`) -- Review dependencies before adding them -- Run security linters locally before pushing -- Report any concerns about existing code - ---- - -## Additional Resources - -- [Our PGP Public Key](https://github.com/hyperpolymath.gpg) -- [Security Advisories](https://github.com/hyperpolymath/social-media-polygraph/security/advisories) -- [Changelog](CHANGELOG.md) -- [Contributing Guidelines](CONTRIBUTING.md) -- [CVE Database](https://cve.mitre.org/) -- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) - ---- - -## Contact - -| Purpose | Contact | -|---------|---------| -| **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/social-media-polygraph/security/advisories/new) or j.d.a.jewell@open.ac.uk | -| **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/social-media-polygraph/discussions) | -| **Other enquiries** | See [README](README.md) for contact information | - ---- - -## Policy Changes - -This security policy may be updated from time to time. Significant changes will be: - -- Committed to this repository with a clear commit message -- Noted in the changelog -- Announced via GitHub Discussions (for major changes) - ---- - -*Thank you for helping keep Social Media Polygraph and its users safe.* 🛡️ - ---- - -Last updated: 2026 · Policy version: 1.0.0 diff --git a/docs/API.md b/docs/API.adoc similarity index 61% rename from docs/API.md rename to docs/API.adoc index 6ae6c9a..ad31212 100644 --- a/docs/API.md +++ b/docs/API.adoc @@ -1,18 +1,19 @@ -# API Documentation +== API Documentation -## Base URL +=== Base URL -``` +.... http://localhost:8000/api/v1 -``` +.... -## Authentication +=== Authentication The API supports two authentication methods: -### 1. JWT Bearer Token +==== 1. JWT Bearer Token -```bash +[source,bash] +---- # Login to get token curl -X POST "http://localhost:8000/api/v1/auth/login" \ -H "Content-Type: application/x-www-form-urlencoded" \ @@ -21,30 +22,32 @@ curl -X POST "http://localhost:8000/api/v1/auth/login" \ # Use token in requests curl -X GET "http://localhost:8000/api/v1/auth/me" \ -H "Authorization: Bearer YOUR_TOKEN" -``` +---- -### 2. API Key +==== 2. API Key -```bash +[source,bash] +---- curl -X POST "http://localhost:8000/api/v1/claims/verify" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text": "claim to verify"}' -``` +---- -## Endpoints +=== Endpoints -### Claims +==== Claims -#### Verify Claim +===== Verify Claim Verify a social media claim. -**Endpoint:** `POST /claims/verify` +*Endpoint:* `+POST /claims/verify+` -**Request:** +*Request:* -```json +[source,json] +---- { "text": "The claim text to verify", "url": "https://example.com/post", @@ -52,11 +55,12 @@ Verify a social media claim. "author": "@username", "metadata": {} } -``` +---- -**Response:** +*Response:* -```json +[source,json] +---- { "success": true, "claim_id": "abc123", @@ -92,30 +96,30 @@ Verify a social media claim. }, "processing_time": 1.234 } -``` +---- -#### Get Claim +===== Get Claim Get analysis for a previously verified claim. -**Endpoint:** `GET /claims/{claim_id}` +*Endpoint:* `+GET /claims/{claim_id}+` -**Response:** Same as verification response analysis object. +*Response:* Same as verification response analysis object. -#### List Claims +===== List Claims List all claims with pagination. -**Endpoint:** `GET /claims/` +*Endpoint:* `+GET /claims/+` -**Query Parameters:** -- `skip` (int, default: 0): Number of records to skip -- `limit` (int, default: 100, max: 1000): Maximum records to return -- `status` (string, optional): Filter by status +*Query Parameters:* - `+skip+` (int, default: 0): Number of records to +skip - `+limit+` (int, default: 100, max: 1000): Maximum records to +return - `+status+` (string, optional): Filter by status -**Response:** +*Response:* -```json +[source,json] +---- [ { "id": "abc123", @@ -124,17 +128,18 @@ List all claims with pagination. "created_at": "2024-01-15T12:00:00" } ] -``` +---- -#### Get Claim History +===== Get Claim History Get temporal history of claim verifications. -**Endpoint:** `GET /claims/{claim_id}/history` +*Endpoint:* `+GET /claims/{claim_id}/history+` -**Response:** +*Response:* -```json +[source,json] +---- [ { "verified_at": "2024-01-15T12:00:00", @@ -143,30 +148,32 @@ Get temporal history of claim verifications. "credibility_score": 0.8 } ] -``` +---- -### Authentication +==== Authentication -#### Register +===== Register Create a new user account. -**Endpoint:** `POST /auth/register` +*Endpoint:* `+POST /auth/register+` -**Request:** +*Request:* -```json +[source,json] +---- { "email": "user@example.com", "username": "username", "password": "secure_password", "full_name": "Full Name" } -``` +---- -**Response:** +*Response:* -```json +[source,json] +---- { "id": "user123", "email": "user@example.com", @@ -174,42 +181,44 @@ Create a new user account. "is_active": true, "created_at": "2024-01-15T12:00:00" } -``` +---- -#### Login +===== Login Authenticate and receive JWT tokens. -**Endpoint:** `POST /auth/login` +*Endpoint:* `+POST /auth/login+` -**Request (form data):** +*Request (form data):* -``` +.... username=user@example.com password=secure_password -``` +.... -**Response:** +*Response:* -```json +[source,json] +---- { "access_token": "eyJ...", "refresh_token": "eyJ...", "token_type": "bearer" } -``` +---- -#### Get Current User +===== Get Current User Get authenticated user information. -**Endpoint:** `GET /auth/me` +*Endpoint:* `+GET /auth/me+` -**Headers:** `Authorization: Bearer YOUR_TOKEN` +*Headers:* `+Authorization: Bearer YOUR_TOKEN+` -**Response:** +*Response:* -```json +[source,json] +---- { "id": "user123", "email": "user@example.com", @@ -217,28 +226,30 @@ Get authenticated user information. "full_name": "Full Name", "is_active": true } -``` +---- -#### Create API Key +===== Create API Key Generate a new API key. -**Endpoint:** `POST /auth/api-keys` +*Endpoint:* `+POST /auth/api-keys+` -**Headers:** `Authorization: Bearer YOUR_TOKEN` +*Headers:* `+Authorization: Bearer YOUR_TOKEN+` -**Request:** +*Request:* -```json +[source,json] +---- { "name": "My API Key", "rate_limit": 100 } -``` +---- -**Response:** +*Response:* -```json +[source,json] +---- { "api_key": { "id": "key123", @@ -249,44 +260,40 @@ Generate a new API key. }, "key": "sk_abc123..." } -``` +---- -**Note:** The actual key is only shown once! +*Note:* The actual key is only shown once! -## Rate Limiting +=== Rate Limiting -API endpoints are rate-limited: -- Default: 100 requests per minute -- Custom limits can be set per API key +API endpoints are rate-limited: - Default: 100 requests per minute - +Custom limits can be set per API key Rate limit headers: -``` + +.... X-RateLimit-Limit: 100 X-RateLimit-Remaining: 95 X-RateLimit-Reset: 1640000000 -``` +.... -## Error Responses +=== Error Responses All error responses follow this format: -```json +[source,json] +---- { "detail": "Error message", "status_code": 400 } -``` +---- -Common error codes: -- `400` - Bad Request -- `401` - Unauthorized -- `403` - Forbidden -- `404` - Not Found -- `429` - Too Many Requests -- `500` - Internal Server Error +Common error codes: - `+400+` - Bad Request - `+401+` - Unauthorized - +`+403+` - Forbidden - `+404+` - Not Found - `+429+` - Too Many Requests +- `+500+` - Internal Server Error -## Webhooks (Coming Soon) +=== Webhooks (Coming Soon) -Subscribe to events: -- `claim.verified` - When a claim is verified -- `claim.updated` - When claim status changes +Subscribe to events: - `+claim.verified+` - When a claim is verified - +`+claim.updated+` - When claim status changes diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.adoc similarity index 63% rename from docs/ARCHITECTURE.md rename to docs/ARCHITECTURE.adoc index d8602e5..09a0d84 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.adoc @@ -1,12 +1,13 @@ -# Architecture Documentation +== Architecture Documentation -## System Overview +=== System Overview -Social Media Polygraph is a microservices-based application for AI-powered fact-checking. +Social Media Polygraph is a microservices-based application for +AI-powered fact-checking. -## High-Level Architecture +=== High-Level Architecture -``` +.... ┌─────────────────────────────────────────────────────────┐ │ Clients │ │ ┌───────────┐ ┌───────────┐ ┌──────────────────┐ │ @@ -46,50 +47,34 @@ Social Media Polygraph is a microservices-based application for AI-powered fact- │ ArangoDB │ │ XTDB │ │ Dragonfly │ │ (Graph) │ │ (Time) │ │ (Cache) │ └──────────┘ └────────┘ └─────────────┘ -``` - -## Components - -### 1. Frontend (React + TypeScript) - -**Responsibilities:** -- User interface for claim verification -- Display of verification results -- User authentication -- Claim history visualization - -**Technology:** -- React 18 with TypeScript -- Vite for build -- TailwindCSS for styling -- React Query for data fetching -- React Router for navigation - -**Key Files:** -- `src/pages/` - Page components -- `src/components/` - Reusable components -- `src/services/api.ts` - API client -- `src/types/` - TypeScript types - -### 2. Backend (FastAPI + Python) - -**Responsibilities:** -- API endpoints -- Business logic -- ML/NLP processing -- Data persistence -- Authentication & authorization - -**Technology:** -- FastAPI (async web framework) -- Pydantic for validation -- spaCy for NLP -- JWT for authentication -- Poetry for dependencies - -**Architecture Layers:** - -``` +.... + +=== Components + +==== 1. Frontend (React + TypeScript) + +*Responsibilities:* - User interface for claim verification - Display of +verification results - User authentication - Claim history visualization + +*Technology:* - React 18 with TypeScript - Vite for build - TailwindCSS +for styling - React Query for data fetching - React Router for +navigation + +*Key Files:* - `+src/pages/+` - Page components - `+src/components/+` - +Reusable components - `+src/services/api.ts+` - API client - +`+src/types/+` - TypeScript types + +==== 2. Backend (FastAPI + Python) + +*Responsibilities:* - API endpoints - Business logic - ML/NLP processing +- Data persistence - Authentication & authorization + +*Technology:* - FastAPI (async web framework) - Pydantic for validation +- spaCy for NLP - JWT for authentication - Poetry for dependencies + +*Architecture Layers:* + +.... ┌─────────────────────────────────┐ │ API Layer │ │ - Endpoints │ @@ -118,85 +103,60 @@ Social Media Polygraph is a microservices-based application for AI-powered fact- │ - XTDB client │ │ - Cache manager │ └─────────────────────────────────┘ -``` +.... -### 3. Databases +==== 3. Databases -#### ArangoDB (Multi-Model) +===== ArangoDB (Multi-Model) -**Purpose:** Primary data store +*Purpose:* Primary data store -**Collections:** -- `claims` - Claim documents -- `sources` - Source credibility data -- `fact_checks` - Fact-check results -- `users` - User accounts -- `api_keys` - API key management +*Collections:* - `+claims+` - Claim documents - `+sources+` - Source +credibility data - `+fact_checks+` - Fact-check results - `+users+` - +User accounts - `+api_keys+` - API key management -**Graph:** -- `knowledge_graph` - Relationships between claims, sources, entities +*Graph:* - `+knowledge_graph+` - Relationships between claims, sources, +entities -**Advantages:** -- Document + Graph in one system -- Flexible schema -- AQL query language -- Built-in graph traversal +*Advantages:* - Document + Graph in one system - Flexible schema - AQL +query language - Built-in graph traversal -#### XTDB (Temporal) +===== XTDB (Temporal) -**Purpose:** Temporal claim tracking +*Purpose:* Temporal claim tracking -**Use Cases:** -- Track claim verification changes over time -- Audit trail -- Historical analysis -- Trend detection +*Use Cases:* - Track claim verification changes over time - Audit trail +- Historical analysis - Trend detection -**Advantages:** -- Immutable event log -- Time-travel queries -- Full history retention +*Advantages:* - Immutable event log - Time-travel queries - Full history +retention -#### Dragonfly (Cache) +===== Dragonfly (Cache) -**Purpose:** High-performance caching +*Purpose:* High-performance caching -**Cached Data:** -- Verification results -- API responses -- NLP processing results -- External API calls +*Cached Data:* - Verification results - API responses - NLP processing +results - External API calls -**Advantages:** -- Redis-compatible -- Lower memory usage -- Better performance -- Simpler deployment +*Advantages:* - Redis-compatible - Lower memory usage - Better +performance - Simpler deployment -### 4. Browser Extension +==== 4. Browser Extension -**Responsibilities:** -- In-context verification on social media -- Quick claim lookup -- Background processing +*Responsibilities:* - In-context verification on social media - Quick +claim lookup - Background processing -**Components:** -- Background service worker -- Content scripts (injected into pages) -- Popup UI -- Options page +*Components:* - Background service worker - Content scripts (injected +into pages) - Popup UI - Options page -**Supported Platforms:** -- Twitter/X -- Facebook -- Instagram -- (Extensible to others) +*Supported Platforms:* - Twitter/X - Facebook - Instagram - (Extensible +to others) -## Data Flow +=== Data Flow -### Claim Verification Flow +==== Claim Verification Flow -``` +.... 1. User Input ↓ 2. API Endpoint (/claims/verify) @@ -230,13 +190,13 @@ Social Media Polygraph is a microservices-based application for AI-powered fact- 9. Cache Result (Dragonfly) ↓ 10. Return Response -``` +.... -## Security Architecture +=== Security Architecture -### Authentication +==== Authentication -``` +.... ┌──────────────────────────────────┐ │ Client │ └────────┬─────────────────────────┘ @@ -262,69 +222,60 @@ Social Media Polygraph is a microservices-based application for AI-powered fact- │ - Extract user context │ │ - Process request │ └──────────────────────────────────┘ -``` - -### Authorization Levels +.... -1. **Public** - No authentication required - - Health checks - - Info endpoints +==== Authorization Levels -2. **Authenticated** - JWT or API key required - - Claim verification - - User profile +[arabic] +. *Public* - No authentication required +* Health checks +* Info endpoints +. *Authenticated* - JWT or API key required +* Claim verification +* User profile +. *Admin* - Superuser required +* User management +* System configuration -3. **Admin** - Superuser required - - User management - - System configuration +=== Scalability -## Scalability +==== Horizontal Scaling -### Horizontal Scaling - -**Backend:** -- Stateless design -- Multiple instances behind load balancer +*Backend:* - Stateless design - Multiple instances behind load balancer - Session data in cache/database -**Databases:** -- ArangoDB: Cluster mode -- XTDB: Distributed deployment -- Dragonfly: Replication +*Databases:* - ArangoDB: Cluster mode - XTDB: Distributed deployment - +Dragonfly: Replication + +==== Caching Strategy -### Caching Strategy +*Levels:* 1. Application cache (in-memory) 2. Dragonfly (distributed +cache) 3. CDN (static assets) -**Levels:** -1. Application cache (in-memory) -2. Dragonfly (distributed cache) -3. CDN (static assets) +*Cache Keys:* -**Cache Keys:** -``` +.... claim:verification:{claim_id} claim:text_hash:{hash} fact_check:{claim_text_hash} user:{user_id} -``` +.... + +*TTL Strategy:* - Verification results: 1 hour - User data: 15 minutes - +Fact-check results: 6 hours -**TTL Strategy:** -- Verification results: 1 hour -- User data: 15 minutes -- Fact-check results: 6 hours +=== Monitoring & Observability -## Monitoring & Observability +==== Logging -### Logging +*Levels:* - DEBUG: Development only - INFO: Normal operations - WARNING: +Potential issues - ERROR: Errors requiring attention - CRITICAL: System +failures -**Levels:** -- DEBUG: Development only -- INFO: Normal operations -- WARNING: Potential issues -- ERROR: Errors requiring attention -- CRITICAL: System failures +*Structured Logging:* -**Structured Logging:** -```json +[source,json] +---- { "timestamp": "2024-01-15T12:00:00", "level": "INFO", @@ -333,40 +284,29 @@ user:{user_id} "claim_id": "abc123", "duration": 1.234 } -``` +---- -### Metrics +==== Metrics -**Application:** -- Request rate -- Response time -- Error rate -- Cache hit rate +*Application:* - Request rate - Response time - Error rate - Cache hit +rate -**Business:** -- Claims verified -- Verification accuracy -- User registrations +*Business:* - Claims verified - Verification accuracy - User +registrations -**Infrastructure:** -- CPU usage -- Memory usage -- Disk I/O -- Network traffic +*Infrastructure:* - CPU usage - Memory usage - Disk I/O - Network +traffic -### Health Checks +==== Health Checks -**Endpoint:** `/health` +*Endpoint:* `+/health+` -**Checks:** -- Database connectivity -- Cache connectivity -- ML model availability -- External API status +*Checks:* - Database connectivity - Cache connectivity - ML model +availability - External API status -## Development Workflow +=== Development Workflow -``` +.... ┌─────────────┐ │ Developer │ └──────┬──────┘ @@ -388,49 +328,50 @@ user:{user_id} ┌─────────────────┐ │ Production │ └─────────────────┘ -``` +.... -## Technology Decisions +=== Technology Decisions -### Why ArangoDB? +==== Why ArangoDB? -- Multi-model (document + graph) -- Claims and sources have relationships -- Flexible schema for varied data -- Strong query language (AQL) +* Multi-model (document + graph) +* Claims and sources have relationships +* Flexible schema for varied data +* Strong query language (AQL) -### Why XTDB? +==== Why XTDB? -- Temporal tracking crucial for fact-checking -- Immutable audit trail -- Historical analysis capabilities +* Temporal tracking crucial for fact-checking +* Immutable audit trail +* Historical analysis capabilities -### Why Dragonfly over Redis? +==== Why Dragonfly over Redis? -- Better performance -- Lower memory footprint -- Redis-compatible (drop-in replacement) -- Active development +* Better performance +* Lower memory footprint +* Redis-compatible (drop-in replacement) +* Active development -### Why FastAPI? +==== Why FastAPI? -- Async/await support -- Automatic API documentation -- Type checking with Pydantic -- Modern Python web framework +* Async/await support +* Automatic API documentation +* Type checking with Pydantic +* Modern Python web framework -### Why React? +==== Why React? -- Component-based architecture -- Large ecosystem -- TypeScript support -- Performant +* Component-based architecture +* Large ecosystem +* TypeScript support +* Performant -## Future Improvements +=== Future Improvements -1. **Message Queue** - Add Celery/RabbitMQ for background jobs -2. **Real-time Updates** - WebSocket support -3. **GraphQL API** - Alternative to REST -4. **Microservices** - Split into smaller services -5. **Service Mesh** - For advanced networking -6. **Event Sourcing** - More comprehensive event tracking +[arabic] +. *Message Queue* - Add Celery/RabbitMQ for background jobs +. *Real-time Updates* - WebSocket support +. *GraphQL API* - Alternative to REST +. *Microservices* - Split into smaller services +. *Service Mesh* - For advanced networking +. *Event Sourcing* - More comprehensive event tracking diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.adoc similarity index 72% rename from docs/DEPLOYMENT.md rename to docs/DEPLOYMENT.adoc index a6382e5..4a15d7a 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.adoc @@ -1,17 +1,18 @@ -# Deployment Guide +== Deployment Guide -## Prerequisites +=== Prerequisites -- Server with Linux (Ubuntu 22.04+ recommended) -- Podman or Docker installed -- Domain name configured (for production) -- SSL certificate (Let's Encrypt recommended) +* Server with Linux (Ubuntu 22.04+ recommended) +* Podman or Docker installed +* Domain name configured (for production) +* SSL certificate (Let’s Encrypt recommended) -## Production Deployment with Podman Compose +=== Production Deployment with Podman Compose -### 1. Server Setup +==== 1. Server Setup -```bash +[source,bash] +---- # Update system sudo apt update && sudo apt upgrade -y @@ -20,30 +21,33 @@ sudo apt install -y podman podman-compose # Install other dependencies sudo apt install -y git nginx certbot python3-certbot-nginx -``` +---- -### 2. Clone Repository +==== 2. Clone Repository -```bash +[source,bash] +---- cd /opt sudo git clone https://github.com/hyperpolymath/social-media-polygraph.git cd social-media-polygraph -``` +---- -### 3. Configure Environment +==== 3. Configure Environment -```bash +[source,bash] +---- # Copy and edit environment files cd infrastructure/podman cp .env.example .env # Edit .env with production values nano .env -``` +---- -**Important production settings:** +*Important production settings:* -```env +[source,env] +---- # Generate strong secrets SECRET_KEY=$(openssl rand -hex 32) JWT_SECRET_KEY=$(openssl rand -hex 32) @@ -58,11 +62,12 @@ ARANGO_ROOT_PASSWORD=$(openssl rand -base64 24) # Disable debug DEBUG=false ENVIRONMENT=production -``` +---- -### 4. Start Services +==== 4. Start Services -```bash +[source,bash] +---- # Start all services podman-compose up -d @@ -71,15 +76,17 @@ podman-compose ps # View logs podman-compose logs -f -``` +---- -### 5. Configure Nginx Reverse Proxy +==== 5. Configure Nginx Reverse Proxy -```bash +[source,bash] +---- sudo nano /etc/nginx/sites-available/polygraph -``` +---- -```nginx +[source,nginx] +---- # Backend API server { listen 80; @@ -107,9 +114,10 @@ server { proxy_set_header X-Forwarded-Proto $scheme; } } -``` +---- -```bash +[source,bash] +---- # Enable site sudo ln -s /etc/nginx/sites-available/polygraph /etc/nginx/sites-enabled/ @@ -118,22 +126,24 @@ sudo nginx -t # Restart Nginx sudo systemctl restart nginx -``` +---- -### 6. SSL with Let's Encrypt +==== 6. SSL with Let’s Encrypt -```bash +[source,bash] +---- # Obtain certificates sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com sudo certbot --nginx -d api.yourdomain.com # Auto-renewal is set up automatically sudo systemctl status certbot.timer -``` +---- -### 7. Firewall Configuration +==== 7. Firewall Configuration -```bash +[source,bash] +---- # Allow HTTP, HTTPS, and SSH sudo ufw allow 22/tcp sudo ufw allow 80/tcp @@ -141,13 +151,14 @@ sudo ufw allow 443/tcp # Enable firewall sudo ufw enable -``` +---- -## Database Initialization +=== Database Initialization -### ArangoDB +==== ArangoDB -```bash +[source,bash] +---- # Access ArangoDB web interface # https://api.yourdomain.com:8529 @@ -155,17 +166,19 @@ sudo ufw enable podman exec -it polygraph-arangodb arangosh # Create initial admin user, databases, etc. -``` +---- -### Backups +==== Backups Create backup script: -```bash +[source,bash] +---- sudo nano /opt/backup-polygraph.sh -``` +---- -```bash +[source,bash] +---- #!/bin/bash BACKUP_DIR="/opt/backups/polygraph" DATE=$(date +%Y%m%d_%H%M%S) @@ -190,31 +203,34 @@ podman cp polygraph-xtdb:/tmp/xtdb_backup.tar.gz \ find $BACKUP_DIR -type f -mtime +30 -delete echo "Backup completed: $DATE" -``` +---- -```bash +[source,bash] +---- # Make executable sudo chmod +x /opt/backup-polygraph.sh # Add to crontab (daily at 2 AM) echo "0 2 * * * /opt/backup-polygraph.sh" | sudo crontab - -``` +---- -## Monitoring +=== Monitoring -### System Monitoring +==== System Monitoring -```bash +[source,bash] +---- # Install monitoring tools sudo apt install -y prometheus prometheus-node-exporter grafana # Configure Prometheus sudo nano /etc/prometheus/prometheus.yml -``` +---- -### Application Logs +==== Application Logs -```bash +[source,bash] +---- # View all logs podman-compose logs -f @@ -223,13 +239,14 @@ podman-compose logs -f backend # Export logs to file podman-compose logs > /var/log/polygraph.log -``` +---- -### Health Checks +==== Health Checks Create monitoring script: -```bash +[source,bash] +---- #!/bin/bash # /opt/health-check.sh @@ -248,25 +265,27 @@ else echo "Frontend: FAILED" # Send alert fi -``` +---- -## Scaling +=== Scaling -### Horizontal Scaling +==== Horizontal Scaling For high traffic, run multiple backend instances: -```yaml +[source,yaml] +---- # In compose.yaml services: backend: deploy: replicas: 3 -``` +---- Use load balancer (Nginx): -```nginx +[source,nginx] +---- upstream backend { least_conn; server localhost:8000; @@ -279,33 +298,34 @@ server { proxy_pass http://backend; } } -``` +---- -### Database Scaling +==== Database Scaling -- **ArangoDB**: Set up cluster mode -- **Dragonfly**: Configure replication -- **XTDB**: Use distributed deployment +* *ArangoDB*: Set up cluster mode +* *Dragonfly*: Configure replication +* *XTDB*: Use distributed deployment -## Security Checklist +=== Security Checklist -- [ ] Change all default passwords -- [ ] Use strong secret keys -- [ ] Enable firewall -- [ ] Configure SSL/TLS -- [ ] Set up regular backups -- [ ] Enable fail2ban for SSH -- [ ] Configure rate limiting -- [ ] Set up monitoring and alerts -- [ ] Review and update dependencies regularly -- [ ] Enable audit logging -- [ ] Implement least-privilege access +* [ ] Change all default passwords +* [ ] Use strong secret keys +* [ ] Enable firewall +* [ ] Configure SSL/TLS +* [ ] Set up regular backups +* [ ] Enable fail2ban for SSH +* [ ] Configure rate limiting +* [ ] Set up monitoring and alerts +* [ ] Review and update dependencies regularly +* [ ] Enable audit logging +* [ ] Implement least-privilege access -## Troubleshooting +=== Troubleshooting -### Container won't start +==== Container won’t start -```bash +[source,bash] +---- # Check logs podman logs polygraph-backend @@ -314,21 +334,23 @@ podman events # Restart service podman-compose restart backend -``` +---- -### Database connection issues +==== Database connection issues -```bash +[source,bash] +---- # Check database is running podman ps | grep arango # Test connection podman exec -it polygraph-backend python -c "from app.db import arango_manager; arango_manager.connect()" -``` +---- -### Performance issues +==== Performance issues -```bash +[source,bash] +---- # Check resource usage podman stats @@ -337,11 +359,12 @@ df -h # Check memory free -h -``` +---- -## Updating +=== Updating -```bash +[source,bash] +---- # Pull latest code cd /opt/social-media-polygraph sudo git pull @@ -355,11 +378,12 @@ podman-compose up -d # Check logs podman-compose logs -f -``` +---- -## Rollback +=== Rollback -```bash +[source,bash] +---- # Stop containers podman-compose down @@ -369,4 +393,4 @@ git checkout # Rebuild and start podman-compose build podman-compose up -d -``` +---- diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..2bf98de --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — social-media-polygraph — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+NONE+` +|Manifest licence |`+NONE+` +|Body classifier |`+MPL-2.0-pure+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |518 +|`+docs/+` files |4 +|`+docs/+` LoC |1136 +|CHANGELOG.md |N +|CONTRIBUTING.md |N +|CODE_OF_CONDUCT.md |N +|SECURITY.md |N +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +518 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 1181737..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — social-media-polygraph — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `NONE` | -| Manifest licence | `NONE` | -| Body classifier | `MPL-2.0-pure` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 518 | -| `docs/` files | 4 | -| `docs/` LoC | 1136 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | N | -| CODE_OF_CONDUCT.md | N | -| SECURITY.md | N | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 518 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/infrastructure/configs/ssl/README.adoc b/infrastructure/configs/ssl/README.adoc new file mode 100644 index 0000000..2b9fa03 --- /dev/null +++ b/infrastructure/configs/ssl/README.adoc @@ -0,0 +1,120 @@ +== SSL Certificate Configuration + +=== Production Setup + +For production environments, you should use Let’s Encrypt or another +trusted certificate authority. + +==== Option 1: Let’s Encrypt with Certbot + +[source,bash] +---- +# Install certbot +sudo apt-get install certbot python3-certbot-nginx + +# Obtain certificate +sudo certbot certonly --webroot \ + -w /var/www/certbot \ + -d yourdomain.com \ + -d www.yourdomain.com + +# Copy certificates to this directory +sudo cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem ./cert.pem +sudo cp /etc/letsencrypt/live/yourdomain.com/privkey.pem ./key.pem +---- + +==== Option 2: Commercial Certificate + +Place your certificate files in this directory: - `+cert.pem+` - Your +SSL certificate (or fullchain) - `+key.pem+` - Your private key + +==== Development Setup + +For local development, you can generate self-signed certificates: + +[source,bash] +---- +cd infrastructure/configs/ssl + +# Generate self-signed certificate (valid for 365 days) +openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ + -keyout key.pem \ + -out cert.pem \ + -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost" + +# Set proper permissions +chmod 600 key.pem +chmod 644 cert.pem +---- + +=== Certificate Rotation + +Certificates should be rotated before expiration. Let’s Encrypt +certificates expire after 90 days. + +==== Automated Renewal (Let’s Encrypt) + +Add to crontab: + +[source,bash] +---- +0 0 * * * certbot renew --quiet && cp /etc/letsencrypt/live/yourdomain.com/*.pem /path/to/ssl/ && podman-compose restart nginx +---- + +=== Security Best Practices + +[arabic] +. *Private Key Protection* +* Never commit `+key.pem+` to version control +* Set restrictive file permissions (600) +* Use HSM for production keys if possible +. *Certificate Monitoring* +* Monitor certificate expiration +* Set up alerts 30 days before expiration +* Use certificate transparency monitoring +. *Strong Ciphers* +* The nginx.conf is configured with modern cipher suites +* TLS 1.2 and 1.3 only +* HSTS enabled with 1-year max-age +. *OCSP Stapling* +* Enabled in nginx configuration +* Improves performance and privacy + +=== Troubleshooting + +==== Certificate Verification + +[source,bash] +---- +# Check certificate +openssl x509 -in cert.pem -text -noout + +# Verify certificate and key match +openssl x509 -noout -modulus -in cert.pem | openssl md5 +openssl rsa -noout -modulus -in key.pem | openssl md5 +---- + +==== Test SSL Configuration + +[source,bash] +---- +# Using openssl +openssl s_client -connect localhost:443 -servername yourdomain.com + +# Using curl +curl -vI https://localhost + +# Online tools (production only) +# - SSL Labs: https://www.ssllabs.com/ssltest/ +# - Mozilla Observatory: https://observatory.mozilla.org/ +---- + +=== Files in this Directory + +* `+README.md+` - This file +* `+cert.pem+` - SSL certificate (gitignored) +* `+key.pem+` - Private key (gitignored) +* `+.gitkeep+` - Keep directory in git + +*IMPORTANT*: Never commit actual certificate or key files to version +control! diff --git a/infrastructure/configs/ssl/README.md b/infrastructure/configs/ssl/README.md deleted file mode 100644 index d37b83a..0000000 --- a/infrastructure/configs/ssl/README.md +++ /dev/null @@ -1,114 +0,0 @@ -# SSL Certificate Configuration - -## Production Setup - -For production environments, you should use Let's Encrypt or another trusted certificate authority. - -### Option 1: Let's Encrypt with Certbot - -```bash -# Install certbot -sudo apt-get install certbot python3-certbot-nginx - -# Obtain certificate -sudo certbot certonly --webroot \ - -w /var/www/certbot \ - -d yourdomain.com \ - -d www.yourdomain.com - -# Copy certificates to this directory -sudo cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem ./cert.pem -sudo cp /etc/letsencrypt/live/yourdomain.com/privkey.pem ./key.pem -``` - -### Option 2: Commercial Certificate - -Place your certificate files in this directory: -- `cert.pem` - Your SSL certificate (or fullchain) -- `key.pem` - Your private key - -### Development Setup - -For local development, you can generate self-signed certificates: - -```bash -cd infrastructure/configs/ssl - -# Generate self-signed certificate (valid for 365 days) -openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ - -keyout key.pem \ - -out cert.pem \ - -subj "/C=US/ST=State/L=City/O=Organization/CN=localhost" - -# Set proper permissions -chmod 600 key.pem -chmod 644 cert.pem -``` - -## Certificate Rotation - -Certificates should be rotated before expiration. Let's Encrypt certificates expire after 90 days. - -### Automated Renewal (Let's Encrypt) - -Add to crontab: -```bash -0 0 * * * certbot renew --quiet && cp /etc/letsencrypt/live/yourdomain.com/*.pem /path/to/ssl/ && podman-compose restart nginx -``` - -## Security Best Practices - -1. **Private Key Protection** - - Never commit `key.pem` to version control - - Set restrictive file permissions (600) - - Use HSM for production keys if possible - -2. **Certificate Monitoring** - - Monitor certificate expiration - - Set up alerts 30 days before expiration - - Use certificate transparency monitoring - -3. **Strong Ciphers** - - The nginx.conf is configured with modern cipher suites - - TLS 1.2 and 1.3 only - - HSTS enabled with 1-year max-age - -4. **OCSP Stapling** - - Enabled in nginx configuration - - Improves performance and privacy - -## Troubleshooting - -### Certificate Verification - -```bash -# Check certificate -openssl x509 -in cert.pem -text -noout - -# Verify certificate and key match -openssl x509 -noout -modulus -in cert.pem | openssl md5 -openssl rsa -noout -modulus -in key.pem | openssl md5 -``` - -### Test SSL Configuration - -```bash -# Using openssl -openssl s_client -connect localhost:443 -servername yourdomain.com - -# Using curl -curl -vI https://localhost - -# Online tools (production only) -# - SSL Labs: https://www.ssllabs.com/ssltest/ -# - Mozilla Observatory: https://observatory.mozilla.org/ -``` - -## Files in this Directory - -- `README.md` - This file -- `cert.pem` - SSL certificate (gitignored) -- `key.pem` - Private key (gitignored) -- `.gitkeep` - Keep directory in git - -**IMPORTANT**: Never commit actual certificate or key files to version control!