{"id":25826903,"url":"https://github.com/basicmachines-co/basic-foundation","last_synced_at":"2025-08-01T02:16:27.294Z","repository":{"id":215508710,"uuid":"738307988","full_name":"basicmachines-co/basic-foundation","owner":"basicmachines-co","description":"Basic Foundation is a Python starter kit for building full-stack SaaS applications with  FastAPI, PostgreSQL, and HTMX. ","archived":false,"fork":false,"pushed_at":"2024-11-18T23:18:10.000Z","size":2292,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-14T11:42:47.963Z","etag":null,"topics":["fastapi","htmx","postgresql","python","saas-admin","saas-api","saas-application","saas-boilerplate","sqlalchemy","tailwindcss"],"latest_commit_sha":null,"homepage":"","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/basicmachines-co.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-01-02T23:41:37.000Z","updated_at":"2025-06-12T06:56:05.000Z","dependencies_parsed_at":"2024-01-21T00:31:13.929Z","dependency_job_id":"170a5a07-2f36-40eb-bd8e-128d7cb1e7dd","html_url":"https://github.com/basicmachines-co/basic-foundation","commit_stats":null,"previous_names":["basicmachines-co/basic-foundation"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/basicmachines-co/basic-foundation","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fbasic-foundation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fbasic-foundation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fbasic-foundation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fbasic-foundation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/basicmachines-co","download_url":"https://codeload.github.com/basicmachines-co/basic-foundation/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/basicmachines-co%2Fbasic-foundation/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268157898,"owners_count":24204763,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-01T02:00:08.611Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","htmx","postgresql","python","saas-admin","saas-api","saas-application","saas-boilerplate","sqlalchemy","tailwindcss"],"created_at":"2025-02-28T15:45:37.073Z","updated_at":"2025-08-01T02:16:27.229Z","avatar_url":"https://github.com/basicmachines-co.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Basic Foundation\n\n![Build Status](https://github.com/basicmachines-co/basic-foundation/actions/workflows/basic-foundation-test.yml/badge.svg)\n![License](https://img.shields.io/github/license/basicmachines-co/basic-foundation)\n![Version](https://img.shields.io/github/v/release/basicmachines-co/basic-foundation)\n![Coverage](https://codecov.io/gh/basicmachines-co/basic-foundation/branch/main/graph/badge.svg)\n\n## Overview\n\nBasic Foundation is a Python framework for building full-stack SaaS applications. It provides user authentication, APIs,\nand user management using modern Python technologies, including FastAPI, PostgreSQL, and HTMX.\n\n## Tech Stack\n\n- **Modern Python**: Python 3.12 for improved typing support, error messages, and performance.\n- **Type Hints and Type Checking**: Comprehensive type hints with Pyright configured for type checking during\n  development.\n- **Async FastAPI**: All API operations are implemented asynchronously using `async`/`await` and non-blocking I/O.\n- **PostgreSQL**: Database layer for persistence.\n- **SQLAlchemy**: Async DB layer with SQLAlchemy 2.0 for ORM.\n- **HTMX**: Frontend admin web app with dynamic interactions via HTMX.\n- **TailwindCSS**: Utility-first styling for the admin interface.\n- **Testing**: Comprehensive test coverage for core app and API using Pytest.\n- **Playwright**: End-to-end in-browser testing for the admin web app.\n\n## Features\n\n- **Asynchronous API Implementation**: FastAPI for non-blocking I/O and async database access.\n- **JWT Authentication**: Secure token-based authentication for both API and web endpoints.\n- **RESTful API Module**: Comprehensive user management and authentication via API.\n- **Responsive Web UI**: Server-side rendered admin UI with partial page updates using Jinja2 templates and HTMX.\n- **TailwindCSS**: Modular and customizable styles using TailwindCSS.\n- **Email Integration**: SMTP support for sending account-related emails (password recovery, activation).\n- **Docker Compose**: Configured for local development with Postgres 15.\n- **DBMate for Migrations**: Easy schema migrations with DBMate, including schema versioning, rollback, and SQL schema\n  dumping.\n- **Transactional Tests**: Rollback transaction after each test to ensure isolated test environments.\n- **100% Test Coverage**: Test coverage measurement with reporting via Coverage.py.\n- **End-to-End Testing**: Playwright tests for frontend functionality, including interactive elements.\n- **CI/CD with GitHub Actions**: Automated testing, versioning, and deployment with GitHub Actions. Releases include\n  version bumps, migrations, and automated deployment (Render.com).\n- **Preview Environments**: Each branch or pull request is deployed to an isolated environment via Render.com.\n\n## Developers\n\nThis framework was created as a starter kit for building SaaS applications. It contains essential features for any\nplatform, such as user authentication and management. There are lots of other similar projects already (\nsee [References]), but they did not have some of the features that I was really looking for, including modern async\nPython, fully featured testing, and HTMX integration for building full-stack web apps. Additionally, I've added elements\nbased on my software engineering experience that are essential for maintainable projects, like continuous integration,\nrobust testing, and release automation and deployment.\n\nThe goal of this project is to provide a starting point for building applications using my preferred technology stack (\nFastAPI, SQLAlchemy, Postgres, HTMX) without having to reinvent the wheel for every feature. I've incorporated a lot of\nlearnings from other projects and designed patterns that are meant to be extensible and maintainable.\n\n### Good Code (Instead of No-Code)\n\nBasic Foundation is designed to encourage writing maintainable, high-quality code. Instead of focusing on low-code or\nno-code solutions, this project prioritizes clarity, explicitness, and structure that can easily be extended or\nmodified. This is essential for developers to maintain full control over their code without relying on black-box\nsolutions.\n\n### FastAPI and HTMX for Server-Side Full-Stack Web Apps\n\nHTMX allows for dynamic updates to web pages without the need for heavy front-end frameworks. By focusing on server-side\nrendering with partial updates, HTMX provides the interactivity expected in modern applications while still leaving\napplication logic on the server. FastAPI, because it's based on Starlette, is well suited to creating HTML-based\nendpoints to handle partial data updates and deliver HTML back to the client to update the DOM in the browser. This\nproject contains implementation examples for many HTMX patterns, including click-to-edit, lazy loading, notifications,\ndialogs, and dynamic partial elements.\n\n### Modular Project Structure\n\nThe codebase is organized into modules that separate concerns cleanly. Each module contains its own routes, business\nlogic, and tests. This modularity makes it easy to add new features or swap out parts of the stack without affecting the\ncore of the application. Database access, basic CRUD operations, pagination, and security are already implemented.\nDevelopers can also create new modules or services as needed, with clear patterns to follow.\n\n### Easy Deployment to Cloud Environments\n\nThe project is built with deployment in mind. Using Docker and GitHub Actions, you can easily set up automated\ndeployment pipelines to cloud platforms like Render.com. Preview environments are automatically generated for each pull\nrequest, making it easier to test and view changes in a live environment before merging.\n\n### Own All of Your Own Data and Essential Features\n\nThere are many options for managing users and authentication, including third-party applications and services. I've used\nsome in the past and have always found it to be a mistake ([Auth0](https://auth0.com/)). Users and authentication are\ncore functionalities for most SaaS applications and too important to outsource. They are tightly integrated with every\npart of the application stack. They are also easy to get wrong, with severe security consequences. At the same time,\nauthentication and user management do not deliver much value on their own. Frameworks like FastAPI\nhave [great information](https://fastapi.tiangolo.com/tutorial/security/first-steps/) on how to build security and\nauthentication, but it still takes time and can be tricky.\n\n### Postgres for All the Data\n\nPostgreSQL is used for persistent data storage because it is reliable, performant, flexible, and available everywhere.\nThe project is set up with PostgreSQL 15 for development via Docker Compose, offering advanced features like JSONB,\nfull-text search, and many other features. DBMate handles schema migrations easily using only SQL. The database schema\nis managed outside of application code.\n\n### Test Everything\n\nBasic Foundation includes comprehensive testing with Pytest and Playwright to ensure your app is reliable. Tests cover\nall core functionality, including authentication, API endpoints, and frontend interactions. Transactional tests ensure\neach test runs in isolation, rolling back database changes at the end of every test (except for Playwright tests).\nCoverage reports ensure that important parts of the codebase aren’t missed.\n\n### MIT License\n\nBasic Foundation takes a lot of inspiration from other works and is licensed to be used freely under the MIT License,\nallowing anyone to use, modify, and distribute it, including for commercial purposes. By choosing an open-source\nframework, you avoid being locked into commercial SaaS starter frameworks. This project provides the flexibility and\nfreedom to build your project on your own terms, without licensing or vendor lock-in.\n\n## References\n\n- https://github.com/fastapi/full-stack-fastapi-template\n- https://github.com/whythawk/full-stack-fastapi-postgresql/blob/master/docs/development-guide.md\n- https://github.com/mjhea0/awesome-fastapi\n- https://max.engineer/server-informed-ui\n- https://htmx.org/essays/splitting-your-apis/\n- https://htmx.org/essays/why-tend-not-to-use-content-negotiation/\n\n## Contributing\n\nContributions are welcome! If you’re interested in contributing to Basic Foundation, follow these steps:\n\n1. **Fork the repository** and clone it locally.\n2. **Create a new branch** for your feature or bugfix.\n3. **Ensure tests pass** and add new tests where needed.\n4. **Submit a pull request** with a clear explanation of your changes.\n\nPlease check the [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.\n\n## Requirements\n\n- Python (3.12): required for generics and type hinting\n- Docker/Docker compose: run Postgres instance locally via Docker Compose\n- GitHub: the `gh` [CLI tool](https://cli.github.com/) is used for releases\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasicmachines-co%2Fbasic-foundation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasicmachines-co%2Fbasic-foundation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasicmachines-co%2Fbasic-foundation/lists"}