Developer Guide

Developer Guide

Overview

Complete guide for developers contributing to the AutoBot Solutions Forum.

Development Environment Setup

Prerequisites

• Python 3.8 or higher
• PostgreSQL 12 or higher
• Git
• Virtual environment tool

Setup Steps

1. Clone Repository

git clone https://github.com/AutoBotSolutions/repo-forum.git
cd repo-forum

2. Create Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

4. Configure Environment

cp .env.example .env
# Edit .env with your settings

5. Initialize Database

python init_db.py

6. Run Development Server

python run.py

Access at http://localhost:5000

Project Structure

repo-forum/
├── app/
│   ├── __init__.py          # Application factory
│   ├── models.py            # Database models
│   ├── template_filters.py  # Custom Jinja2 filters
│   ├── static/              # Static assets
│   ├── templates/           # Jinja2 templates
│   ├── auth/                # Authentication module
│   ├── forum/               # Forum module
│   ├── admin/               # Admin module
│   ├── user/                # User module
│   ├── notification/        # Notification module
│   ├── message/             # Messaging module
│   ├── api/                 # API module
│   └── main/                # Main routes
├── migrations/              # Database migrations
├── docs/                    # Documentation
├── config.py                # Configuration
├── run.py                   # Development server
├── init_db.py               # Database initialization
└── requirements.txt         # Python dependencies

Code Style

Python Style

• Follow PEP 8 guidelines
• Use meaningful variable names
• Add docstrings to functions
• Keep functions focused
• Maximum line length: 100 characters

HTML/Jinja2 Style

• Use meaningful template names
• Keep templates modular
• Use template inheritance
• Add comments for complex logic

CSS Style

• Use CSS custom properties
• Organize by component
• Use BEM naming convention
• Ensure responsive design

Development Workflow

Branching Strategy

• main - Production code
• develop - Development branch
• feature/* - Feature branches
• bugfix/* - Bug fix branches

Creating a Feature Branch

git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

Committing Changes

git add .
git commit -m "feat: description of your feature"

Commit Message Convention

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation
• style: - Code style
• refactor: - Refactoring
• test: - Tests
• chore: - Maintenance

Database Migrations

Creating a Migration

flask db migrate -m "description"

Applying Migrations

flask db upgrade

Rolling Back

flask db downgrade

Testing

Running Tests

pytest

Writing Tests

• Write unit tests for functions
• Write integration tests for routes
• Aim for >80% coverage
• Use descriptive test names

Common Development Tasks

Adding a New Route

1. Add route function in appropriate blueprint
2. Create template if needed
3. Add form if needed
4. Update models if needed
5. Add authentication/decorators
6. Add rate limiting
7. Test the route

Adding a New Model

1. Add model to models.py
2. Create migration
3. Apply migration
4. Add relationships
5. Create admin routes (if needed)
6. Update templates

Adding a New Form

1. Create form class in forms.py
2. Add validators
3. Add CSRF protection
4. Create template with form
5. Handle form submission
6. Add flash messages

Adding a New Blueprint

1. Create blueprint directory
2. Add __init__.py
3. Create routes.py
4. Create forms.py (if needed)
5. Register blueprint in app/__init__.py
6. Create templates directory

Debugging

Enabling Debug Mode

app.run(debug=True)

Viewing Logs

tail -f logs/app.log

Database Queries

from flask_sqlalchemy import get_debug_queries
for query in get_debug_queries():
    print(query.statement, query.parameters, query.duration)

Common Issues

Import Errors

• Check virtual environment is activated
• Verify dependencies are installed
• Check Python path

Database Errors

• Verify PostgreSQL is running
• Check DATABASE_URL in .env
• Ensure database exists

Template Errors

• Check template path
• Verify template syntax
• Check context variables

Performance Optimization

Database Optimization

• Use indexed columns
• Optimize queries
• Use lazy loading
• Add query limits

Caching (Future)

• Implement Redis caching
• Cache query results
• Cache static assets
• Use CDN

Frontend Optimization

• Minify CSS/JS
• Optimize images
• Use lazy loading
• Enable compression

Security Best Practices

Input Validation

• Validate all user input
• Sanitize data
• Use parameterized queries
• Never trust user input

Authentication

• Use secure password hashing
• Implement CSRF protection
• Use rate limiting
• Secure session cookies

Data Protection

• Hash passwords
• Encrypt sensitive data
• Use HTTPS in production
• Secure environment variables

Contributing

Pull Request Process

1. Fork the repository
2. Create feature branch
3. Make your changes
4. Write tests
5. Update documentation
6. Submit pull request

Pull Request Checklist

• Code follows style guidelines
• Tests pass locally
• Documentation updated
• No new warnings
• Commit messages follow convention

Resources

Documentation

• Architecture-System.md
• Database-System.md
• API-System.md
• Security-System.md

External Resources

• Flask Documentation
• SQLAlchemy Documentation
• Jinja2 Documentation
• PostgreSQL Documentation

Getting Help

• Check existing documentation
• Search GitHub issues
• Join Discord community
• Email dev@autobotsolutions.com