Development Workflow

Local Environment Setup

To begin contributing to Atslegas, ensure your local environment is configured to match the application's requirements.

Virtual Environment

It is recommended to use a Python virtual environment to manage dependencies:

# Create a virtual environment
python -m venv venv

# Activate it (Windows)
.\venv\Scripts\activate

# Activate it (Linux/macOS)
source venv/bin/activate

# Install development dependencies
pip install -r requirements.txt

Configuration for Development

The application relies on config.json for environment-specific settings. For local development, ensure your client_sessions path is writable:

"client_sessions": {
    "timeout_seconds": 3600,
    "session_storage_dir": "%s/flask_session"
}

Note: The application automatically attempts to clear the flask_session directory on startup during the initialization phase in main.py.

Working with the Database

Atslegas uses SQLite with Write-Ahead Logging (WAL) mode enabled to handle concurrency.

Schema Modifications

The database is initialized using schema.sql. If you need to modify the table structures:

1. Update schema.sql.
2. Delete the existing database.db file (if data is disposable).
3. Run python main.py to trigger the automatic schema creation.

Manual Database Access

You can interact with the database using any SQLite client. The application uses PRAGMA busy_timeout = 5000 to prevent locking issues during development.

Development Workflow & Debugging

Bypassing Authentication

During active frontend development or API testing, you may find it necessary to bypass session checks. In api_server.py, there is a conditional block within the @api_bp.before_request handler:

# Temporary bypass for development
elif request.endpoint not in [...] and 1==1: 
    # Current code may have auth check disabled via '1==1'

Warning: Ensure this is reverted to proper session validation (session.get('user_id')) before staging or production use.

Managing Backups

The project maintains a dev_bkps/ directory. This is used for storing stable versions of core logic before experimental changes.

• Creating a backup: Copy critical files like api_server.py or db_engine.py to dev_bkps/ with a version suffix (e.g., -bkp1.py).
• Restoring: If an experimental feature breaks the database engine, replace the root file with the backup version.

Logging

The DB class in db_engine.py includes a built-in logging system. You can adjust the verbosity by changing the log_level attribute:

• 0: No logs.
• 1: Errors only.
• 2: All operations (default for development).

database = db_engine.DB()
database.log_level = 2 # Increase verbosity for debugging SQL queries

Testing API Endpoints

The API uses JSON for all requests and responses. For testing, use a tool like Postman or curl.

Example: Testing User Creation

curl -X POST http://127.0.0.1:5000/api/user/add \
     -H "Content-Type: application/json" \
     -d '{"username": "testuser", "password": "password123"}'

Session Handling in Tests

Because the app uses flask-session (filesystem-based), your testing client must support cookie persistence to maintain a session between login and subsequent API calls.

Frontend Development

The frontend is split into admin-front and user-front.

• Static Assets: All JS and CSS files are served from the frontend/ directory.
• Dynamic Rendering: Most UI elements are rendered via JavaScript using data fetched from the /api/ endpoints.
• Local Storage: The admin dashboard caches some data in localStorage (defined in admin-common.js) to reduce API overhead. Clear your browser's local storage if you encounter inconsistent UI states after database resets.