!!! warning "Project status: active development"
**OSSS is still being developed.** Community input and assistance are very welcome!
- Share feedback and ideas via issues or discussions.
- Open PRs for bug fixes and small improvements.
# Open Source School Software (OSSS)
A community-driven, modular suite of applications for K-12 districts.
> 📚 **Live documentation:** https://rubelw.github.io/OSSS/
This repository is a **polyglot monorepo** with a Next.js frontend (`src/osss-web`) and a FastAPI
backend (`src/OSSS`). Documentation is built with **MkDocs Material**, with API references
generated from source:
- **Frontend (TypeScript)** → TypeDoc → Markdown (`docs/api/web/*`)
- **Backend (Python)** → mkdocstrings renders code objects from `src/OSSS`
- **REST (OpenAPI)** → exported JSON rendered with ReDoc
The static site is output to `./documentation/`.
---
## Why This Is Important
When Artificial General Intelligence (AGI) starts to emerge—potentially by 2030—districts will need to adjust governance, safety filters, and curricula rapidly. That kind of agility is exactly what community-maintained, open-source software delivers—without waiting on a vendor roadmap. Today, many incumbent systems are tied to legacy architectures and slow release cycles. While AI is already reshaping mainstream apps, most school platforms haven’t meaningfully evolved to leverage it.
I’m building the next generation of school software as an open, participatory project. Administrators, staff, students, and families will be able to propose enhancements, contribute code, and ship improvements together—so the platform keeps pace with classroom needs and policy changes.
---
## 📖 Documentation Quick Start
> Run all commands from the **repo root**. Create and activate a Python venv first.
> Live docs are published at **https://rubelw.github.io/OSSS/**.
### Quick start
```bash
# clone
git clone https://github.com/rubelw/OSSS.git
cd OSSS
# (optional) copy environment examples
cp .env.example .env || true
# create a venv in a folder named .venv (inside your project)
python3 -m venv .venv
source .venv/bin/activate
# build + run local stack (database, API, web)
./start_osss.sh
# to run the cli
osss <TAB>
# Keycloak http://localhost:8085 with username 'admin' and password 'admin'
# FastApi http://localhost:8081/docs# username 'activities_director@osss.local' and password 'password'
# Web: http://localhost:3000 username 'activities_director@osss.local' and password 'password'
```
Build the static site to `./documentation/`:
```bash
# Optional: regenerate TypeDoc first if code changed
npx typedoc --options typedoc.frontend.json
mkdocs build --clean
```
---
## 📁 Docs Layout (MkDocs)
```
docs/
├─ index.md # Landing page
├─ frontend/
│ └─ overview.md # Next.js app overview
├─ backend/
│ └─ overview.md # FastAPI app overview
├─ api/
│ ├─ web/ # (generated) TypeDoc markdown for Next.js
│ └─ openapi/ # (generated) openapi.json for ReDoc
└─ api/python/
├─ index.md # (generated) landing for Python API
└─ OSSS.md # (generated) mkdocstrings page for OSSS package
```
> The pages under `docs/api/python/` and `docs/api/openapi/` are created during the MkDocs build by
> small helper scripts (see below). TypeDoc output is generated before the build runs.
---
## Demo
## ⚙️ MkDocs Configuration
`mkdocs.yml` at the repo root glues everything together. Key bits:
```yaml
site_name: OSSS Developer Documentation
site_url: https://rubelw.github.io/OSSS/
docs_dir: docs
site_dir: documentation
nav:
- Overview: index.md
- Frontend (Next.js):
- Overview: frontend/overview.md
- API (TypeScript): api/web/modules.md # <-- match what TypeDoc emits (modules.md or index.md)
- Backend (Python):
- Overview: backend/overview.md
- API (Python): api/python/OSSS.md
- OpenAPI: backend/openapi.md
plugins:
- search
- mkdocstrings:
handlers:
python:
paths: ["src"] # import OSSS from ./src/OSSS
options:
show_source: false
docstring_style: google
members_order: source
- gen-files:
scripts:
- tooling/generate_docs.py
- tooling/export_openapi.py
# Optional: make pages wider site-wide, or include a page-class-based override
extra_css:
- overrides/wide.css
# Load ReDoc globally so the OpenAPI page can initialize it
extra_javascript:
- https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js
```
### Helper scripts (run during `mkdocs serve/build`)
- `tooling/generate_docs.py` — generates `docs/api/python/OSSS.md` that contains the `::: OSSS`
directive; mkdocstrings renders it into API docs.
```python
# tooling/generate_docs.py
from pathlib import Path
import mkdocs_gen_files as gen
with gen.open("api/python/index.md", "w") as f:
f.write("# Python API\n\n- [OSSS package](./OSSS.md)\n")
with gen.open("api/python/OSSS.md", "w") as f:
f.write("# `OSSS` package\n\n")
f.write("::: OSSS\n")
f.write(" handler: python\n")
f.write(" options:\n")
f.write(" show_root_heading: true\n")
f.write(" show_source: false\n")
f.write(" docstring_style: google\n")
f.write(" members_order: source\n")
f.write(" show_signature: true\n")
```
- `tooling/export_openapi.py` — writes `docs/api/openapi/openapi.json` from the FastAPI app.
```python
# tooling/export_openapi.py
import json
import mkdocs_gen_files as gen
from OSSS.main import app # adjust if your FastAPI app lives elsewhere
with gen.open("api/openapi/openapi.json", "w") as f:
json.dump(app.openapi(), f, indent=2)
```
### ReDoc page (`docs/backend/openapi.md`)
```md
---
title: OSSS API (OpenAPI)
hide:
- toc
class: full-width
---
> If the panel below stays blank, verify the JSON exists:
> **[OpenAPI JSON](../../api/openapi/openapi.json)**
<div id="redoc-container"></div>
<script>
(function () {
function init() {
var el = document.getElementById('redoc-container');
if (window.Redoc && el) {
// NOTE: two ".." segments from /backend/openapi → /api/openapi/openapi.json
window.Redoc.init('../../api/openapi/openapi.json', {}, el);
} else {
setTimeout(init, 50);
}
}
init();
})();
</script>
<noscript>
JavaScript is required to render the ReDoc UI. You can still download the
<a href="../../api/openapi/openapi.json">OpenAPI JSON</a>.
</noscript>
```
### Optional: widen pages
`docs/overrides/wide.css` (site-wide) or `docs/overrides/redoc-wide.css` (only OpenAPI page):
```css
/* Site-wide wider grid */
.md-grid { max-width: 1440px; }
/* Only pages with class: full-width */
.md-content__inner.full-width { max-width: none; padding-left: 0; padding-right: 0; }
#redoc-container { margin: 0; padding: 0; }
```
Reference in `mkdocs.yml` via `extra_css`.
---
## 🔐 Environment Notes
- **Python imports for docs**: run `mkdocs` with `PYTHONPATH=src` so mkdocstrings and the OpenAPI
export can import `OSSS` from `src/OSSS`.
- **Frontend generator**: TypeDoc runs with your Next.js `tsconfig`. If the app declares
"packageManager" in `src/osss-web/package.json`, use **npm** (not pnpm) for consistency.
---
## 🧪 CI Example (GitHub Actions)
`.github/workflows/docs.yml`
```yaml
name: Build Docs
on:
push:
branches: [ main ]
workflow_dispatch:
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Install deps
run: |
python -m pip install --upgrade pip
pip install -r requirements-docs.txt
npm ci || npm i
- name: Generate TypeScript API (TypeDoc → Markdown)
run: npx typedoc --options typedoc.frontend.json
- name: Build MkDocs site → ./documentation
env:
PYTHONPATH: src
run: mkdocs build --clean
- name: Upload artifact
uses: actions/upload-artifact@v4
with:
name: osss-docs
path: documentation
```
---
## 📜 License
Apache-2.0 (see `LICENSE`).
Raw data
{
"_id": null,
"home_page": null,
"name": "open-schools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Will Rubel <will.rubel@gmail.com>",
"keywords": "Keycloak, FastAPI, Authentication, Authorization, School",
"author": null,
"author_email": "Will Rubel <will.rubel@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/20/eb/cbdd42ef1e23bb438ec54e550ce407a1919535843562a8988fce56d8e1fa/open_schools-0.0.0.dev2.tar.gz",
"platform": null,
"description": "!!! warning \"Project status: active development\"\n **OSSS is still being developed.** Community input and assistance are very welcome!\n - Share feedback and ideas via issues or discussions.\n - Open PRs for bug fixes and small improvements.\n\n# Open Source School Software (OSSS)\n\nA community-driven, modular suite of applications for K-12 districts.\n\n> \ud83d\udcda **Live documentation:** https://rubelw.github.io/OSSS/\n\nThis repository is a **polyglot monorepo** with a Next.js frontend (`src/osss-web`) and a FastAPI\nbackend (`src/OSSS`). Documentation is built with **MkDocs Material**, with API references\ngenerated from source:\n\n- **Frontend (TypeScript)** \u2192 TypeDoc \u2192 Markdown (`docs/api/web/*`)\n- **Backend (Python)** \u2192 mkdocstrings renders code objects from `src/OSSS`\n- **REST (OpenAPI)** \u2192 exported JSON rendered with ReDoc\n\nThe static site is output to `./documentation/`.\n\n\n\n---\n\n## Why This Is Important\n\nWhen Artificial General Intelligence (AGI) starts to emerge\u2014potentially by 2030\u2014districts will need to adjust governance, safety filters, and curricula rapidly. That kind of agility is exactly what community-maintained, open-source software delivers\u2014without waiting on a vendor roadmap. Today, many incumbent systems are tied to legacy architectures and slow release cycles. While AI is already reshaping mainstream apps, most school platforms haven\u2019t meaningfully evolved to leverage it.\n\nI\u2019m building the next generation of school software as an open, participatory project. Administrators, staff, students, and families will be able to propose enhancements, contribute code, and ship improvements together\u2014so the platform keeps pace with classroom needs and policy changes.\n\n---\n\n## \ud83d\udcd6 Documentation Quick Start\n\n> Run all commands from the **repo root**. Create and activate a Python venv first. \n> Live docs are published at **https://rubelw.github.io/OSSS/**.\n\n### Quick start\n```bash\n# clone\ngit clone https://github.com/rubelw/OSSS.git\ncd OSSS\n\n# (optional) copy environment examples\ncp .env.example .env || true\n\n# create a venv in a folder named .venv (inside your project)\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# build + run local stack (database, API, web)\n./start_osss.sh\n\n# to run the cli\nosss <TAB>\n\n# Keycloak http://localhost:8085 with username 'admin' and password 'admin'\n# FastApi http://localhost:8081/docs# username 'activities_director@osss.local' and password 'password'\n# Web: http://localhost:3000 username 'activities_director@osss.local' and password 'password'\n```\n\nBuild the static site to `./documentation/`:\n\n```bash\n# Optional: regenerate TypeDoc first if code changed\nnpx typedoc --options typedoc.frontend.json\nmkdocs build --clean\n```\n\n---\n\n## \ud83d\udcc1 Docs Layout (MkDocs)\n\n```\ndocs/\n\u251c\u2500 index.md # Landing page\n\u251c\u2500 frontend/\n\u2502 \u2514\u2500 overview.md # Next.js app overview\n\u251c\u2500 backend/\n\u2502 \u2514\u2500 overview.md # FastAPI app overview\n\u251c\u2500 api/\n\u2502 \u251c\u2500 web/ # (generated) TypeDoc markdown for Next.js\n\u2502 \u2514\u2500 openapi/ # (generated) openapi.json for ReDoc\n\u2514\u2500 api/python/\n \u251c\u2500 index.md # (generated) landing for Python API\n \u2514\u2500 OSSS.md # (generated) mkdocstrings page for OSSS package\n```\n\n> The pages under `docs/api/python/` and `docs/api/openapi/` are created during the MkDocs build by\n> small helper scripts (see below). TypeDoc output is generated before the build runs.\n\n---\n\n## Demo\n\n\n\n\n## \u2699\ufe0f MkDocs Configuration\n\n`mkdocs.yml` at the repo root glues everything together. Key bits:\n\n```yaml\nsite_name: OSSS Developer Documentation\nsite_url: https://rubelw.github.io/OSSS/\ndocs_dir: docs\nsite_dir: documentation\n\nnav:\n - Overview: index.md\n - Frontend (Next.js):\n - Overview: frontend/overview.md\n - API (TypeScript): api/web/modules.md # <-- match what TypeDoc emits (modules.md or index.md)\n - Backend (Python):\n - Overview: backend/overview.md\n - API (Python): api/python/OSSS.md\n - OpenAPI: backend/openapi.md\n\nplugins:\n - search\n - mkdocstrings:\n handlers:\n python:\n paths: [\"src\"] # import OSSS from ./src/OSSS\n options:\n show_source: false\n docstring_style: google\n members_order: source\n - gen-files:\n scripts:\n - tooling/generate_docs.py\n - tooling/export_openapi.py\n\n# Optional: make pages wider site-wide, or include a page-class-based override\nextra_css:\n - overrides/wide.css\n\n# Load ReDoc globally so the OpenAPI page can initialize it\nextra_javascript:\n - https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js\n```\n\n### Helper scripts (run during `mkdocs serve/build`)\n\n- `tooling/generate_docs.py` \u2014 generates `docs/api/python/OSSS.md` that contains the `::: OSSS`\n directive; mkdocstrings renders it into API docs.\n\n ```python\n # tooling/generate_docs.py\n from pathlib import Path\n import mkdocs_gen_files as gen\n\n with gen.open(\"api/python/index.md\", \"w\") as f:\n f.write(\"# Python API\\n\\n- [OSSS package](./OSSS.md)\\n\")\n\n with gen.open(\"api/python/OSSS.md\", \"w\") as f:\n f.write(\"# `OSSS` package\\n\\n\")\n f.write(\"::: OSSS\\n\")\n f.write(\" handler: python\\n\")\n f.write(\" options:\\n\")\n f.write(\" show_root_heading: true\\n\")\n f.write(\" show_source: false\\n\")\n f.write(\" docstring_style: google\\n\")\n f.write(\" members_order: source\\n\")\n f.write(\" show_signature: true\\n\")\n ```\n\n- `tooling/export_openapi.py` \u2014 writes `docs/api/openapi/openapi.json` from the FastAPI app.\n\n ```python\n # tooling/export_openapi.py\n import json\n import mkdocs_gen_files as gen\n from OSSS.main import app # adjust if your FastAPI app lives elsewhere\n\n with gen.open(\"api/openapi/openapi.json\", \"w\") as f:\n json.dump(app.openapi(), f, indent=2)\n ```\n\n### ReDoc page (`docs/backend/openapi.md`)\n\n```md\n---\ntitle: OSSS API (OpenAPI)\nhide:\n - toc\nclass: full-width\n---\n\n> If the panel below stays blank, verify the JSON exists:\n> **[OpenAPI JSON](../../api/openapi/openapi.json)**\n\n<div id=\"redoc-container\"></div>\n\n<script>\n(function () {\n function init() {\n var el = document.getElementById('redoc-container');\n if (window.Redoc && el) {\n // NOTE: two \"..\" segments from /backend/openapi \u2192 /api/openapi/openapi.json\n window.Redoc.init('../../api/openapi/openapi.json', {}, el);\n } else {\n setTimeout(init, 50);\n }\n }\n init();\n})();\n</script>\n\n<noscript>\nJavaScript is required to render the ReDoc UI. You can still download the\n<a href=\"../../api/openapi/openapi.json\">OpenAPI JSON</a>.\n</noscript>\n```\n\n### Optional: widen pages\n\n`docs/overrides/wide.css` (site-wide) or `docs/overrides/redoc-wide.css` (only OpenAPI page):\n\n```css\n/* Site-wide wider grid */\n.md-grid { max-width: 1440px; }\n\n/* Only pages with class: full-width */\n.md-content__inner.full-width { max-width: none; padding-left: 0; padding-right: 0; }\n#redoc-container { margin: 0; padding: 0; }\n```\n\nReference in `mkdocs.yml` via `extra_css`.\n\n---\n\n## \ud83d\udd10 Environment Notes\n\n- **Python imports for docs**: run `mkdocs` with `PYTHONPATH=src` so mkdocstrings and the OpenAPI\n export can import `OSSS` from `src/OSSS`.\n- **Frontend generator**: TypeDoc runs with your Next.js `tsconfig`. If the app declares\n \"packageManager\" in `src/osss-web/package.json`, use **npm** (not pnpm) for consistency.\n\n---\n\n## \ud83e\uddea CI Example (GitHub Actions)\n\n`.github/workflows/docs.yml`\n\n```yaml\nname: Build Docs\non:\n push:\n branches: [ main ]\n workflow_dispatch:\n\njobs:\n docs:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - uses: actions/setup-node@v4\n with:\n node-version: 20\n\n - uses: actions/setup-python@v5\n with:\n python-version: \"3.11\"\n\n - name: Install deps\n run: |\n python -m pip install --upgrade pip\n pip install -r requirements-docs.txt\n npm ci || npm i\n\n - name: Generate TypeScript API (TypeDoc \u2192 Markdown)\n run: npx typedoc --options typedoc.frontend.json\n\n - name: Build MkDocs site \u2192 ./documentation\n env:\n PYTHONPATH: src\n run: mkdocs build --clean\n\n - name: Upload artifact\n uses: actions/upload-artifact@v4\n with:\n name: osss-docs\n path: documentation\n```\n---\n\n## \ud83d\udcdc License\n\nApache-2.0 (see `LICENSE`).\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Open Source School Software(OSSS)",
"version": "0.0.0.dev2",
"project_urls": {
"documentation": "https://osss.com/",
"issues": "https://github.com/rubelw/OSSS/issues",
"repository": "https://github.com/rubelw/OSSS"
},
"split_keywords": [
"keycloak",
" fastapi",
" authentication",
" authorization",
" school"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3d5e79a0bff0276eaef96f9fc49ad99cf6fb1b93263e1d33a72ba5d9bbd6d362",
"md5": "2b4496b51e9eeae0bc097bb58a88744a",
"sha256": "d12897f76ae1cda801aa8ea97103097ed244ad2d09060a0f88f8741ce29f4df5"
},
"downloads": -1,
"filename": "open_schools-0.0.0.dev2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b4496b51e9eeae0bc097bb58a88744a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 405501,
"upload_time": "2025-08-28T14:42:00",
"upload_time_iso_8601": "2025-08-28T14:42:00.280890Z",
"url": "https://files.pythonhosted.org/packages/3d/5e/79a0bff0276eaef96f9fc49ad99cf6fb1b93263e1d33a72ba5d9bbd6d362/open_schools-0.0.0.dev2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "20ebcbdd42ef1e23bb438ec54e550ce407a1919535843562a8988fce56d8e1fa",
"md5": "2a28b09e679caa3c1f9b4614eb5cc4fe",
"sha256": "174c2c81dee8d66190a122dc1142dafba987efb6b798e0ffede5ab5ff1241f04"
},
"downloads": -1,
"filename": "open_schools-0.0.0.dev2.tar.gz",
"has_sig": false,
"md5_digest": "2a28b09e679caa3c1f9b4614eb5cc4fe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 174226,
"upload_time": "2025-08-28T14:42:02",
"upload_time_iso_8601": "2025-08-28T14:42:02.111556Z",
"url": "https://files.pythonhosted.org/packages/20/eb/cbdd42ef1e23bb438ec54e550ce407a1919535843562a8988fce56d8e1fa/open_schools-0.0.0.dev2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 14:42:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rubelw",
"github_project": "OSSS",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "open-schools"
}
JSON
