core/README.md

GraphQL API Backend

Backend service providing GraphQL API for content management system with reactions, ratings and topics.

📚 Documentation

• API Documentation • Authentication Guide • Caching System • Features Overview

🚀 Core Features

Shouts (Posts)

• CRUD operations via GraphQL mutations
• Rich filtering and sorting options
• Support for multiple authors and topics
• Rating system with likes/dislikes
• Comments and nested replies
• Bookmarks and following

Reactions System

• ReactionKind types: LIKE, DISLIKE, COMMENT
• Rating calculation for shouts and comments
• User-specific reaction tracking
• Reaction stats and aggregations
• Nested comments support

Authors & Topics

• Author profiles with stats
• Topic categorization and hierarchy
• Following system for authors/topics
• Activity tracking and stats
• Community features

🛠️ Tech Stack

Core: Python 3.12 • GraphQL • PostgreSQL • Redis • txtai Server: Starlette • Granian • Nginx Tools: SQLAlchemy • JWT • Pytest • Ruff Deploy: Dokku • Gitea • Glitchtip

🔧 Development

📦 Prepare environment:

python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.dev.txt

🚀 Run server

First, certificates are required to run the server with HTTPS.

mkcert -install
mkcert localhost

Then, run the server:

python -m granian main:app --interface asgi

⚡ Useful Commands

# Linting and import sorting
ruff check . --fix --select I

# Code formatting
ruff format . --line-length=120

# Run tests
pytest

# Type checking
mypy .

# dev run
python -m granian main:app --interface asgi

📝 Code Style

Ruff for linting • 120 char lines • Type hints required • Docstrings for public methods

🔍 GraphQL Development

Test queries in GraphQL Playground at http://localhost:8000:

# Example query
query GetShout($slug: String) {
  get_shout(slug: $slug) {
    id
    title
    main_author {
      name
    }
  }
}

---

📊 Project Stats

🤝 Contributing

• Read the guide

We welcome contributions! Please read our contributing guide before submitting PRs.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• discours.io • Source Code

---

Made with ❤️ by the Discours Team