This project, named PyFundaments, provides a robust and secure Python architecture. Its core mission is not to be a monolithic framework, but to establish a layered, modular foundation—or "fundament"—of essential services. This structure ensures that every application starts on a verified and secure base, with a focus on stability, code clarity, and a security-first mindset from the ground up.

from app.app import start_application
await start_application(fundaments)

• Project Structure
• The Role of main.py
• Configuration (.env)
• Installation
• Getting Started
• Module Documentation
• Notes

├── main.py
├── README.md
├── requirements.txt
├── .gitignore
├── .env.example
├── app/
│   └── (your Python-Module)
│   └── app.py
├── fundaments/
│   ├── access_control.py
│   ├── config_handler.py
│   ├── encryption.py
│   ├── postgresql.py
│   ├── security.py
│   └── user_handler.py
└── docs/
    ├── access_control.py.md
    ├── encryption.py.md
    ├── postgresql.py.md
    ├── security.py.md
    └── user_handler.py.md

main.py is the only entry point and acts as the first line of defense for the application.

• Validate Dependencies: It checks for all necessary core modules in fundaments/ and exits immediately if any are missing.
• Conditional Environment Loading: It uses the config_handler to load available configuration variables and initializes only the services for which configuration is present.
• Initialize Services: It creates instances of available services (PostgreSQL, encryption, access control, user handling) based on environment configuration, collecting them into a single service dictionary.
• Graceful Degradation: Services that cannot be initialized are skipped with warnings, allowing applications to run with partial functionality.
• Decouple App Logic: It hands off the prepared and verified services to app/app.py, allowing the main application to focus purely on its business logic without worrying about low-level setup.

Application settings are managed using a .env file. Never commit this file to version control.

The framework uses conditional loading - only services with available configuration are initialized. This allows different application types to use only what they need.

A .env.example file is provided to show available variables. Create a copy named .env and configure only what your application requires.

# Database connection (required only for database-using apps)
DATABASE_URL="postgresql://user:password@host:port/database?sslmode=require"

# Encryption keys (required only for apps using encryption)
MASTER_ENCRYPTION_KEY="your_256_bit_key_here"
PERSISTENT_ENCRYPTION_SALT="your_unique_salt_here"

# Logging configuration (optional)
LOG_LEVEL="INFO"
LOG_TO_TMP="false"
ENABLE_PUBLIC_LOGS="true"

Discord Bot: Only needs BOT_TOKEN, no database or encryption required. ML Pipeline: Only needs DATABASE_URL for data access. Web Application: May need all services for full functionality.

pip install -r requirements.txt

1. Configure: Create your .env file from the .env.example and set only the variables your application type requires.
2. Run: Execute the main.py script to start the application.

python main.py

The framework will automatically detect available configuration and load only the necessary services.

Each security-relevant core module is documented in the docs/ directory:

This project is licensed under the Apache License 2.0.

This project is released under the permissive Apache 2.0 License, which is intended to provide broad freedom for use and modification.
However, in the interest of fostering a safe and responsible community, we include the following mandatory ethical use restrictions:

Use of this project (or derivatives) is strictly prohibited for purposes that:

• Promote Hatred or Discrimination
  Includes hate speech, incitement to violence, or discrimination based on race, religion, gender, orientation, etc.

• Facilitate Illegal Activities
  Use to conduct or support criminal activity is forbidden.

• Spread Malicious Content
  This includes pornography, malware, spyware, or other harmful payloads.

We believe that freedom in development must be coupled with responsibility.
Violation of these terms constitutes a breach of license and will trigger takedown actions including legal and technical responses.

Volkan Kücükbudak

• Developed and maintained by the PyFundaments project.
• Core components inspired by best practices in modular app architecture and OWASP security principles.
• Third-party libraries are credited in their respective module docs and comply with open-source terms.

Security-first by design.  
If one piece is missing or unsafe — the app does not run.  
Zero tolerance for guesswork.

Give a ⭐ if you find the structure helpful.

1. main.py - Conditional Service Loading

• Added: Environment-based conditional service initialization
• Added: Graceful fallback when services can't be initialized (warning instead of crash)
• Added: Conditional logging configuration (LOG_LEVEL, LOG_TO_TMP, ENABLE_PUBLIC_LOGS)
• Added: Smart dependency management (access_control & user_handler only load if database available)
• Added: Safe shutdown (only close DB pool if it was initialized)
• Result: Framework now supports partial service loading for different app types

2. app/app.py - Proper Service Injection

• Removed: Direct service imports and instantiation
• Added: Services received as parameter from main.py
• Modified: start_application() now takes fundaments dictionary as parameter
• Added: Conditional service usage based on what main.py provides
• Added: Examples for different app types (database-only, database-free modes)
• Result: Clean separation - main.py handles initialization, app.py uses services

3. fundaments/config_handler.py - Universal Configuration Loader

• Removed: REQUIRED_KEYS validation (moved to main.py)
• Modified: Now loads ALL environment variables without validation
• Added: Helper methods: get_bool(), get_int(), has(), get_all()
• Added: Safe defaults and type conversion
• Result: Config handler never needs updates, works with any ENV variables

4. .env.example - Conditional Configuration Template

• Added: Clear separation between core and optional dependencies
• Added: Logging configuration options
• Added: App-specific configuration examples (Discord, ML, Web)
• Added: Comments explaining when to use each option
• Result: Users only configure what they need, no unused variables

• Conditional Loading: Framework only loads needed services based on available ENV vars
• Merge-Safe Structure: User code (app/, config_handler.py) protected from framework updates
• Zero Breaking Changes: Updates only affect fundaments/ directory
• Enterprise-Level Merging: Community can safely pull framework updates</document_content>