Welcome to the Starter App¶

This project is a template application that demonstrates how to build a modern web application using the neuroglia-python framework. It provides a solid foundation for building clean, scalable, and maintainable applications with Python.

Online Documentation

Getting Started¶

To get started with the application, please refer to the Getting Started guide, which will walk you through the installation and setup process.

Key Sections¶

• Architecture: Learn about the core concepts of the application's architecture and the neuroglia-python framework.
• Security: Understand the dual authentication system, including session-based and JWT bearer token flows, plus authorization with OAuth2/OIDC.
• Development: Find information on the development workflow, including the Makefile commands and documentation setup.
• Deployment: Learn how to deploy the application using Docker and other related technologies.

graph TD
    subgraph "FastAPI Application"
        A["Controllers (API Layer)"] --> B["Mediator (Neuroglia)"];
        B --> C{"Handlers (Application Layer)"};
        C --> C1["Commands (Write)"];
        C --> C2["Queries (Read)"];
        C1 --> D["Repositories (Data Access)"];
        C2 --> D;
        D --> E["MongoDB (Persistence)"];
    end

🛠️ Technology Stack¶

Backend¶

• Framework: Neuroglia Python
• Web: FastAPI
• Database: MongoDB with Motor
• Cache: Redis
• Auth: Keycloak

Frontend¶

• Bundler: Parcel
• Templates: Nunjucks
• Styles: Bootstrap 5 + SCSS
• JavaScript: ES6 Modules

Infrastructure¶

• Containers: Docker + Docker Compose
• Observability: OpenTelemetry
• Documentation: MkDocs Material

🤝 Contributing¶

This is a starter app template. When adapting for your project:

Keep the Patterns¶

• ✅ Authentication architecture
• ✅ CQRS structure
• ✅ Dependency injection setup
• ✅ Frontend build pipeline
• ✅ Docker development environment

Customize the Domain¶

• 🔧 Replace Task entities with your models
• 🔧 Update UI components and styling
• 🔧 Configure Keycloak realms and roles
• 🔧 Adapt database schema
• 🔧 Add your API endpoints

Extend as Needed¶

• ➕ Additional auth providers
• ➕ More command/query handlers
• ➕ Event sourcing
• ➕ Background jobs
• ➕ API versioning

📚 Additional Resources¶

Documentation¶

• GitHub Repository
• API Documentation (when running)
• Deployment Guide

External Links¶

• Neuroglia Framework
• FastAPI Docs
• MkDocs Material

🆘 Getting Help¶

1. Check Common Issues
2. Review relevant documentation section
3. Search GitHub Issues
4. Create a new issue with details

Ready to start? Head to the Docker Environment guide to get your development environment running!