docs: add/improve overview pgs for backend, frontend, schema, & SDKs

.pre-commit-config.yaml

@@ -78,6 +78,7 @@ repos:
         args:
           - --fix
         files: \.md$
+        language: system
 
   - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt
     rev: 0.2.3

README.md

@@ -22,7 +22,7 @@
 # [OWASP Nest](https://nest.owasp.org/)
 
 </div>
-
+<!-- --8<-- [start:docs] -->
 **OWASP Nest** is a comprehensive, community-first platform built to enhance collaboration and contribution across the OWASP community. The application serves as a central hub for exploring OWASP projects and ways to contribute to them, empowering contributors to find opportunities that align with their interests and expertise.
 
 Key features of the platform include:
@@ -71,3 +71,4 @@ Over time, OWASP Nest has expanded to address broader OWASP community needs, suc
 - [BlueSky](https://bsky.app/profile/nest.owasp.org)
 - [LinkedIn](https://www.linkedin.com/groups/14656108/)
 - [OWASP Slack](https://owasp.slack.com/archives/project-nest) -- join [#project-nest](https://owasp.org/slack/invite)
+<!-- --8<-- [end:docs] -->

backend/README.md

@@ -0,0 +1,58 @@
+# Backend Overview
+
+The OWASP Nest backend is a Python-based API server built with the [Django](https://www.djangoproject.com/) framework.
+
+## Tech Stack
+
+| Component       | Technology                                      |
+| --------------- | ------------------------------------------------|
+| **Framework**   | Django 6.x                                      |
+| **REST API**    | [Django Ninja](https://django-ninja.dev/)       |
+| **GraphQL API** | [Strawberry GraphQL](https://strawberry.rocks/) |
+| **Database**    | PostgreSQL                                      |
+| **Caching**     | Redis (via `django-redis`)                      |
+| **Task Queue**  | Django RQ                                       |
+| **Search**      | Algolia                                         |
+
+## Directory Structure
+
+The backend code lives in this directory. Key directories include:
+
+- `apps/` - Contains all Django applications (e.g., `owasp`, `github`, `api`).
+- `settings/` - Django configuration files.
+- `tests/` - Automated tests.
+- `data/` - Database dumps and backup files.
+
+## Running Locally
+
+The project uses **Docker** for local development. From the project root:
+
+```bash
+# Start all services (backend, db, cache)
+docker compose -f docker-compose/local/compose.yaml up
+```
+
+For common tasks, use the provided `Makefile` targets:
+
+| Task                    | Command                 |
+| ----------------------- | ----------------------- |
+| Run database migrations | `make migrate`          |
+| Create a superuser      | `make create-superuser` |
+| Run backend tests       | `make test-backend`     |
+| Access Django shell     | `make django-shell`     |
+
+See the root `Makefile` and the local `Makefile` for more targets.
+
+## Key APIs
+
+- **REST API (v0)**: Served at `/api/v0/`. See [API v0 README](https://github.com/OWASP/Nest/blob/main/backend/apps/api/rest/v0/README.md) for SDK-related constraints.
+- **GraphQL API**: Served at `/graphql/`.
+
+## Dependencies
+
+Dependencies are managed with [Poetry](https://python-poetry.org/). The main configuration is in `pyproject.toml`.
+
+```bash
+# Update dependencies
+cd backend && poetry update
+```

backend/apps/api/README.md

@@ -0,0 +1,26 @@
+# API Overview
+
+The OWASP Nest API is divided into two primary interfaces: GraphQL and REST.
+
+## GraphQL API
+
+The GraphQL API is the primary interface used by the OWASP Nest frontend application.
+
+- **Framework**: Built using [Strawberry GraphQL](https://strawberry.rocks/).
+- **Endpoint**: `/graphql/`
+- **Playground**: An interactive GraphiQL interface is automatically available at `/graphql/` when running the backend in development mode (`DJANGO_CONFIGURATION=Local`).
+
+## REST API (v0)
+
+The REST API is used primarily for programmatic access, integrations, and generating client SDKs.
+
+- **Framework**: Built using [Django Ninja](https://django-ninja.dev/).
+- **Base Route**: `/api/v0/`
+- **Schema**: Auto-generated OpenAPI (Swagger) specification is available at `/api/v0/openapi.json`.
+
+### Client SDKs
+
+The OpenAPI specification is used to generate official SDKs in various languages:
+- [OWASP Nest SDKs (Main Repo)](https://github.com/owasp/nest-sdk)
+- [Python SDK](https://github.com/owasp/nest-sdk-python)
+- [TypeScript SDK](https://github.com/OWASP/nest-sdk-typescript)

backend/apps/slack/README.md

@@ -0,0 +1,31 @@
+# Nestbot Overview
+
+Nestbot is the custom Slack integration for the OWASP Nest project, built using the [Slack Bolt for Python](https://docs.slack.dev/tools/bolt-python/getting-started) framework within Django.
+
+## Tech Stack
+
+| Component         | Technology                         |
+| ----------------- | ---------------------------------- |
+| **Framework**     | Slack Bolt (Python)                |
+| **Integration**   | Django (as a standard app)         |
+| **Hosting**       | AWS Lambda (via Zappa)             |
+
+## Directory Structure
+
+The Nestbot code lives in `backend/apps/slack/`. Key directories include:
+
+- `commands/` - Handlers for Slack slash commands (e.g., `/nest`).
+- `events/` - Handlers for Slack events (e.g., when a user joins a channel).
+- `actions/` - Handlers for interactive components (e.g., button clicks).
+- `models/` - Django models for storing Slack workspaces, messages, and users.
+- `templates/` - Slack Block Kit JSON templates for rich messages.
+
+## Key Commands
+
+Run these `Makefile` targets to manage Slack data:
+
+| Task                             | Command                                            |
+| -------------------------------- | -------------------------------------------------- |
+| Sync Slack workspace data        | `make slack-sync-data`                             |
+| Sync recent Slack messages       | `make slack-sync-messages`                         |
+| Export Slack data to JSON        | `make slack-export-data`                           |

docker-compose/local/compose.yaml

@@ -84,6 +84,11 @@ services:
       - 8001:8001
     volumes:
       - ../../docs:/home/owasp/docs
+      - ../../backend:/home/owasp/backend:ro
+      - ../../frontend:/home/owasp/frontend:ro
+      - ../../README.md:/home/owasp/README.md:ro
+      - ../../CODE_OF_CONDUCT.md:/home/owasp/CODE_OF_CONDUCT.md:ro
+      - ../../CONTRIBUTING.md:/home/owasp/CONTRIBUTING.md:ro
       - docs-venv:/home/owasp/.venv
 
   frontend:

docs/api/overview.md

@@ -0,0 +1,17 @@
+--8<-- "backend/apps/api/README.md"
+
+---
+
+## Important Constraints
+
+When contributing to the REST API, follow these rules to avoid breaking SDK generation:
+
+### 1. Unique `operationId`
+
+Each API endpoint **must have a unique `operationId`** in the OpenAPI spec. Duplicate `operationId`s will cause method conflicts in generated SDKs.
+
+### 2. Stable Authentication Class Name
+
+The authentication class in `backend/apps/api/rest/auth/api_key.py` **must be named `ApiKey`**.
+- The client's `api_key` parameter is automatically derived from this class name.
+- **Do not rename this class.**

docs/backend/overview.md

@@ -0,0 +1 @@
+--8<-- "backend/README.md"

docs/code-of-conduct.md

@@ -1,92 +1 @@
-<!-- Disabling MD046 to preserve MkDocs rendering -->
-<!-- markdownlint-disable MD046 -->
-# Code of Conduct
-
-## Our Pledge
-
-!!! quote "Community Pledge"
-    We as members, contributors, and leaders pledge to make participation in our
-    community 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, 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.
-
-## Community Standards
-
-### Positive Behaviors
-
-We encourage behaviors that contribute to a positive environment:
-
-- Demonstrating empathy and kindness toward other people
-- Being respectful of differing opinions, viewpoints, and experiences
-- Giving and gracefully accepting constructive feedback
-- Accepting responsibility and apologizing for mistakes
-- Focusing on what is best for the overall community
-
-### Unacceptable Behaviors
-
-!!! warning "The following behaviors are considered unacceptable"
-    - Use of sexualized language or imagery
-    - Trolling, insulting comments, and personal attacks
-    - Public or private harassment
-    - Publishing others' private information without permission
-    - Other inappropriate conduct in a professional setting
-
-## Enforcement
-
-### Responsibilities
-
-!!! info "Leadership Role"
-
-    Community leaders are responsible for:
-
-    - Clarifying and enforcing standards of acceptable behavior
-    - Taking appropriate and fair corrective action
-    - Removing, editing, or rejecting contributions not aligned with this Code
-    - Communicating moderation decisions when appropriate
-
-### Reporting Process
-
-!!! tip "Reporting Violations"
-    Report instances of unacceptable behavior to the community leaders at:
-    [OWASP Nest Project Leaders](https://owasp.org/www-project-nest)
-
-    All complaints will be reviewed and investigated promptly and fairly.
-
-### Guidelines for Enforcement
-
-Community leaders follow these impact guidelines when determining consequences:
-
-=== "Correction"
-    - **Impact**: Inappropriate or unwelcome behavior
-    - **Response**: Private warning and explanation
-    - **Action**: Public apology may be requested
-
-=== "Warning"
-    - **Impact**: Single incident or series of violations
-    - **Response**: Warning with consequences
-    - **Action**: No interaction for specified period
-
-=== "Temporary Ban"
-    - **Impact**: Serious violation of community standards
-    - **Response**: Temporary ban from community interaction
-    - **Action**: No public or private interaction allowed
-
-=== "Permanent Ban"
-    - **Impact**: Pattern of violations or harassment
-    - **Response**: Permanent ban from community
-    - **Action**: No public interaction within community
-
-## Attribution
-
-This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html), version 2.0, available at [contributor-covenant.org](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html).
-
-Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
-
-!!! note "Additional Resources"
-    - [Contributor Covenant FAQ](https://www.contributor-covenant.org/faq)
-    - [Available Translations](https://www.contributor-covenant.org/translations)
+--8<-- "CODE_OF_CONDUCT.md"