How litestar-org/litestar-fullstack works
Main Components
• Backend API Server:
• Located inside the “src/app” directory. It contains the core application code including the ASGI application entry point (asgi.py), configuration files, and the core server logic.
• Under “src/app/domain”, you have domain-specific modules such as “accounts”, “teams”, “tags”, “system”, etc. These directories represent the various business logic segments.
• The “src/app/db” folder hosts the database connectivity, models, migrations (with Alembic integration), and fixtures.
• The “src/app/lib” provides shared utilities and helper libraries such as encryption, DTO definitions, and exception handling.
• CLI & Management Tools:
• The CLI commands are an extension of the Litestar’s built-in click CLI (as shown by the “app” commands for “database”, “worker”, and “run”). This exposes management functions for running migrations, watching routes, or interacting with background workers.
• Tools in the “tools” directory support documentation building, asset management, and post-build operations.
• Frontend:
• The “resources” directory contains the frontend code powered by Vite. It has subdirectories for pages, layouts, components, contexts, and assets, plus a few TypeScript configuration files like “tsconfig.json” and “vite.config.ts”.
• Jinja2 templates in “src/app/domain/web/templates” integrate with Vite’s development support (like HMR through Webpack/Vite websocket connections).
• Background Task Workers:
• Integration with the SAQ library and dedicated worker commands (see “app worker” command in the README) indicate that background processing is a key component, handling asynchronous tasks alongside the main API server.
• Infrastructure & Deployment:
• The “deploy” and Docker-related files (Dockerfiles, docker-compose.yml, and .dockerignore) indicate a containerized deployment using multi-stage Docker builds (with a distroless option) as well as orchestration for infrastructure (a database and Redis are started via “make start-infra”).
• Tests & Documentation:
• The “tests” folder (with both integration and unit tests) and the “docs” folder (rich in API domain and usage guides) support the project’s quality and maintenance.
Relationships and Interactions Between Components
• The CLI/Management tools serve as interfaces to manage and orchestrate these components (for migrations, asset management, and invoking CLI commands).
Architectural Patterns & Design Principles
• Layered Architecture: Clearly separate concerns where the domain logic is organized in modules (accounts, teams, etc.), the database layer is isolated via SQLAlchemy, and the API controllers use Litestar’s framework paradigms.
• Modular Design: The domain-specific folders indicate adherence to separation of concerns. Each module has its own controllers, guards, schemas, and signals.
• Containerization: The distinct Docker and docker-compose files show a container-first approach for development and production.
• DevOps Integration: CI/CD pipelines are present (as seen in the GitHub workflows) and are an integral part of the system architecture.
Specifying Technologies and Frameworks
• Python (Litestar, SQLAlchemy, Structlog, SAQ).
• Frontend Technologies: Vite, React (implied by TSX and component files) integrated with Jinja2 templates.
• Docker for containerizing the application.
• Testing frameworks (unit and integration tests).
• CI/CD, along with code quality tools (ESLint, Prettier, mypy, Ruff).