{"id":34969465,"url":"https://github.com/bgeneto/fastapi-alpine-starter","last_synced_at":"2026-03-17T17:13:32.680Z","repository":{"id":324950377,"uuid":"1099191900","full_name":"bgeneto/fastapi-alpine-starter","owner":"bgeneto","description":"A template project for bootstrapping an Alpine.js and Python FastAPI application.","archived":false,"fork":false,"pushed_at":"2025-11-27T14:37:41.000Z","size":31957,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-11-29T18:44:27.034Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bgeneto.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-18T17:26:25.000Z","updated_at":"2025-11-27T14:37:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bgeneto/fastapi-alpine-starter","commit_stats":null,"previous_names":["bgeneto/htmx-fastapi-template","bgeneto/alpine-fastapi-template","bgeneto/fastapi-alpine-starter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bgeneto/fastapi-alpine-starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgeneto%2Ffastapi-alpine-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgeneto%2Ffastapi-alpine-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgeneto%2Ffastapi-alpine-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgeneto%2Ffastapi-alpine-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bgeneto","download_url":"https://codeload.github.com/bgeneto/fastapi-alpine-starter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bgeneto%2Ffastapi-alpine-starter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30627923,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T14:16:03.965Z","status":"ssl_error","status_checked_at":"2026-03-17T14:16:03.380Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2025-12-26T23:40:49.600Z","updated_at":"2026-03-17T17:13:32.675Z","avatar_url":"https://github.com/bgeneto.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FastAPI + Alpine.js Starter\n\nA professional, enterprise-grade starter template featuring FastAPI, Alpine.js, and Tailwind CSS with full internationalization (i18n) support.\n\n**Features:**\n- FastAPI with async/await and dependency injection\n- Alpine.js for reactive client-side components\n- Axios for clean, consistent AJAX calls (replaces fetch)\n- HTMX for seamless server-driven HTML updates (prefer Alpine.js + Axios though)\n- **Internationalization (i18n)** - Multi-language support with Babel\n- Pydantic v2 for validation (server-side + client-side)\n- SQLModel (async SQLAlchemy) for DB models and persistence\n- Async DB session management with repository pattern\n- Structured logging with Loguru\n- Environment config via Pydantic BaseSettings\n- Database migrations with Alembic\n- Tailwind CSS 4.x (PostCSS) for modern styling\n- Professional folder structure (templates, static organization)\n- Full authentication system with magic link login\n- Role-based access control (PENDING, USER, MODERATOR, ADMIN)\n\n## 📁 Project Structure\n\n```\nfastapi-alpine-starter/\n├── app/                              # Application core\n│   ├── main.py                       # FastAPI app \u0026 route handlers\n│   ├── config.py                     # Configuration (Pydantic BaseSettings)\n│   ├── models.py                     # SQLModel table definitions\n│   ├── schemas.py                    # Pydantic validation schemas\n│   ├── repository.py                 # Data access layer (CRUD)\n│   ├── auth.py                       # Session \u0026 authentication\n│   ├── email.py                      # Email service (Resend)\n│   ├── i18n.py                       # i18n utilities\n│   ├── logger.py                     # Logging configuration\n│   ├── db.py                         # Database engine \u0026 sessions\n│   └── create_db.py                  # Database initialization\n│\n├── templates/                        # Jinja2 templates\n│   ├── _base.html                    # Root template (layout, head, footer)\n│   ├── components/                   # Reusable components\n│   │   ├── _theme_toggle.html        # Dark/light mode toggle\n│   │   ├── _language_selector.html   # Language selection\n│   │   ├── _form_alpine.html         # Form component with Alpine.js\n│   │   └── _recent_contacts.html     # Recent contacts partial\n│   └── pages/                        # Full-page templates\n│       ├── index.html                # Homepage\n│       ├── auth/                     # Authentication pages\n│       │   ├── login.html            # Magic link login\n│       │   ├── register.html         # User registration\n│       │   └── check_email.html      # Email verification\n│       └── admin/                    # Admin pages\n│           ├── login.html            # Admin password login\n│           ├── index.html            # Admin dashboard\n│           └── users.html            # User management\n│\n├── static/                           # Static assets\n│   ├── css/                          # Stylesheets\n│   │   ├── input.css                 # Tailwind source\n│   │   └── output.css                # Compiled CSS (generated)\n│   ├── icons/                        # SVG icons (Heroicons)\n│   ├── images/                       # Image assets\n│   └── style.css                     # Custom styles\n│\n├── alembic/                          # Database migrations\n│   ├── env.py                        # Migration configuration\n│   └── versions/                     # Migration files\n│\n├── translations/                     # i18n translation files\n│   └── pt_BR/                        # Portuguese (Brazil)\n│       └── LC_MESSAGES/\n│           ├── messages.po           # Translation strings\n│           └── messages.mo           # Compiled translations\n│\n├── docs/                             # Documentation\n│   ├── ARCHITECTURE.md               # Folder structure \u0026 design rationale\n│   ├── AUTHENTICATION.md             # Auth system details\n│   ├── MIGRATIONS.md                 # Database migrations guide\n│   ├── TAILWIND_SETUP.md             # CSS build process\n│   └── I18N.md                       # i18n implementation guide\n│\n├── tests/                            # Test suite\n│   ├── conftest.py                   # Pytest fixtures\n│   └── test_contact.py               # Contact form tests\n│\n├── scripts/                          # Utility scripts\n│   └── pre-commit.sh                 # Git pre-commit hook\n│\n├── Configuration files\n│   ├── pyproject.toml                # Python project metadata\n│   ├── requirements.txt               # Python dependencies\n│   ├── package.json                  # Node.js dependencies\n│   ├── postcss.config.js             # PostCSS configuration\n│   ├── babel.cfg                     # Babel i18n config\n│   ├── alembic.ini                   # Alembic configuration\n│   ├── .env.example                  # Environment variable template\n│   └── .gitignore                    # Git ignore rules\n│\n├── Docker files\n│   ├── Dockerfile                    # Multi-stage Docker build\n│   └── compose.yml                   # Docker Compose config\n│\n├── Scripts\n│   ├── start.py                      # Application startup\n│   ├── setup-tailwind.sh             # Tailwind CSS setup\n│   ├── translate.sh                  # i18n management\n│   └── main.py                       # Entry point\n│\n└── Documentation\n    ├── README.md                     # This file\n    ├── RESTRUCTURING_SUMMARY.md      # Restructuring changes\n    └── .github/\n        ├── copilot-instructions.md   # Development guidelines\n        └── workflows/\n            └── ci.yml                # CI/CD pipeline\n```\n\n### Key Directories Explained\n\n- **app/** - All Python application code (routes, models, business logic)\n- **templates/** - Jinja2 HTML templates, organized by feature (pages, components)\n- **static/css/** - Tailwind CSS files (input source, compiled output)\n- **docs/** - Comprehensive documentation for development and deployment\n- **alembic/** - Database schema evolution and migrations\n- **translations/** - Multi-language support files (auto-generated during build)\n\n## 🌍 Internationalization\n\nThis project includes full i18n support with **automatic detection** and **manual language selector**:\n\n- **Supported Languages**: English (default), Portuguese (pt_BR)\n- **Language Selector UI**: Globe icon in header - click to change language\n- **Auto-detection**: From browser Accept-Language header (works on first visit)\n- **Persistent**: Language choice saved in cookie\n- **Coverage**: All UI strings, validation messages, and dynamic content\n\n**Quick Start:**\n```bash\n# Add a new language\n./translate.sh init es\n\n# Update translations after code changes\n./translate.sh refresh\n```\n\n**Users can switch language:**\n- Click the 🌐 globe icon in the top-right corner\n- Or it auto-detects from browser language on first visit\n\n**📖 Full documentation:** See [docs/I18N.md](docs/I18N.md) for complete i18n guide\n\n## 🚀 Run locally (development)\n\n```bash\n# 1. Python setup\npython -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\n\n# 2. Build Tailwind CSS (required)\nnpm install\nnpm run build:css\n\n# 3. Configure environment\ncp .env.example .env\n# Edit .env with your settings (DATABASE_URL, SECRET_KEY, DEBUG, LOG_FILE)\npython -m app.create_db  # create tables for dev\n\n# 4. Compile translations (required for i18n)\n./translate.sh compile\n\n# 5. Run the app\nuvicorn app.main:app --reload\n```\n\n**For active development**, run Tailwind in watch mode in a separate terminal:\n```bash\nnpm run watch:css  # Auto-rebuilds CSS on template changes\n```\n\n## 🐳 Docker / Docker Compose\n\n**Quick start with Docker Compose:**\n```bash\ndocker-compose up --build\n```\n\nThe Dockerfile automatically:\n- Installs Node.js and npm dependencies\n- Builds Tailwind CSS (creates `static/output.css`)\n- Compiles translations\n- Runs the FastAPI application\n\n**Production Docker build:**\n```bash\ndocker build -t fastapi-alpine-starter .\ndocker run -p 8000:8000 fastapi-alpine-starter\n```\n\n.env example:\n```\nDATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/fastapi_alpine\nSECRET_KEY=change-me\nENV=development\nDEBUG=true\nLOG_FILE=logs/app.log\n```\n\nNotes:\n- For production, run Alembic migrations instead of create_db.\n- Set `DEBUG=true` in `.env` to enable DEBUG-level logging\n- Set `LOG_FILE=logs/app.log` to enable file logging (optional, defaults to console-only)\n- Log files auto-rotate at 10MB, kept for 7 days, and compressed as zip\n- The scaffold focuses on patterns and a clean separation of concerns.\n\nNotes:\n- **Logging**: Set `DEBUG=true` to enable debug logs. Set `LOG_FILE` to enable file logging (rotated at 10MB, kept for 7 days).\n- For production, run Alembic migrations instead of create_db.\n- The scaffold focuses on patterns and a clean separation of concerns.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgeneto%2Ffastapi-alpine-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbgeneto%2Ffastapi-alpine-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbgeneto%2Ffastapi-alpine-starter/lists"}