Python Modular Monolith

A modern full-stack application with a Python FastAPI backend and Supabase integration, following modular monolith architecture principles.

🏗️ Architecture

This project follows a Modular Monolith pattern, where:

• Backend: Python FastAPI with Supabase integration
• Frontend: (To be implemented)
• Database: Supabase (PostgreSQL with real-time features)
• Authentication: Supabase Auth

📁 Project Structure

python-modular-monolith/
├── backend/                 # Python FastAPI backend
│   ├── api.py              # Main FastAPI application
│   ├── config.py           # Configuration management
│   ├── database.py         # Supabase client setup
│   ├── models.py           # Pydantic models
│   ├── services.py         # Business logic layer
│   ├── requirements.txt    # Python dependencies
│   ├── run.py             # Server startup script
│   ├── test_setup.py      # Setup verification
│   ├── env.example        # Environment template
│   └── README.md          # Backend documentation
├── frontend/               # Frontend application (future)
├── .gitignore             # Git ignore rules
└── README.md              # This file

🚀 Quick Start

Prerequisites

• Python 3.11+ (recommended for best compatibility)
• Supabase account and project
• Git

Backend Setup

1. Clone the repository

   git clone <your-repo-url>
   cd python-modular-monolith

2. Set up the backend

   cd backend
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt

3. Configure environment variables

   cp env.example .env
   # Edit .env with your Supabase credentials

4. Start the server

   python run.py

5. Verify setup

   python test_setup.py

API Documentation

Once the server is running, visit:

• Interactive API Docs: http://localhost:8000/docs
• ReDoc Documentation: http://localhost:8000/redoc
• Health Check: http://localhost:8000/health

🔧 Configuration

Environment Variables

Create a .env file in the backend/ directory:

# Supabase Configuration
SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_anon_key

# Server Configuration
HOST=0.0.0.0
PORT=8000
DEBUG=True

Getting Supabase Credentials

1. Go to Supabase Dashboard
2. Select your project
3. Go to Settings → API
4. Copy the Project URL and anon public key

📚 API Endpoints

Authentication

• POST /auth/register - Register a new user
• POST /auth/login - Login user
• POST /auth/logout - Logout user
• POST /auth/refresh - Refresh access token

User Management

• GET /users/me - Get current user info
• PUT /users/me - Update current user
• DELETE /users/me - Delete current user

Admin (User Management)

• GET /admin/users/{user_id} - Get user by ID
• PUT /admin/users/{user_id} - Update user by ID
• DELETE /admin/users/{user_id} - Delete user by ID

Health & Monitoring

• GET /health - Health check
• GET / - Root endpoint

🛠️ Development

Code Structure

The backend follows a clean architecture pattern:

• config.py: Centralized configuration management
• database.py: Supabase client initialization and connection management
• models.py: Pydantic models for request/response validation
• services.py: Business logic layer with UserService and AuthService
• api.py: FastAPI application with route definitions

Adding New Features

1. Models: Add new Pydantic models in models.py
2. Services: Add business logic in services.py
3. Routes: Add new endpoints in api.py
4. Configuration: Add new settings in config.py if needed

Testing

# Run setup tests
python test_setup.py

# Install test dependencies
pip install pytest pytest-asyncio httpx

# Run tests (when implemented)
pytest

🚀 Deployment

Production Setup

1. Set DEBUG=False in environment variables
2. Configure proper CORS origins
3. Use a production WSGI server:

   pip install gunicorn
   gunicorn api:app -w 4 -k uvicorn.workers.UvicornWorker

4. Set up proper logging and monitoring
5. Configure environment variables securely

Docker (Future)

Docker configuration will be added for containerized deployment.

🔒 Security

• JWT-based authentication via Supabase
• Environment variable configuration
• Input validation with Pydantic
• CORS middleware configured
• Secure password handling

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License.

🆘 Troubleshooting

Common Issues

1. Python version compatibility: Use Python 3.11+ for best results
2. Supabase connection errors: Verify your credentials in .env
3. Import errors: Ensure virtual environment is activated
4. Port conflicts: Change PORT in .env if 8000 is in use

Getting Help

• Check the API documentation at /docs
• Review the health endpoint at /health
• Check server logs for detailed error messages

🗺️ Roadmap

• Frontend implementation
• Docker containerization
• CI/CD pipeline
• Comprehensive test suite
• Database migrations
• Real-time features
• API rate limiting
• Monitoring and logging