Development Guide

Development Guide

Project Structure

CS3704-Canvas-Project/
├── src/canvas_tui/       # Application source
│   ├── api.py            # Canvas API client
│   ├── app.py            # Textual app orchestration
│   ├── cache.py          # SQLite persistence
│   ├── cli.py            # Command-line interface
│   ├── config.py         # Configuration management
│   ├── models.py         # Data models
│   ├── state.py          # Application state
│   ├── screens/          # TUI screens
│   │   ├── dashboard.py
│   │   ├── courses.py
│   │   ├── grades.py
│   │   └── ...
│   └── widgets/          # Reusable components
│       ├── charts.py
│       ├── command_bar.py
│       └── ...
├── tests/                 # Test suite
├── docs/                  # Architecture docs
├── docs-site/             # MkDocs source
└── .github/               # Workflows and templates

Coding Standards

Style

• Formatter: Ruff (Black-compatible)
• Line length: 88 characters
• Imports: sorted with isort
• Type hints: encouraged (checked by mypy)

Linting

ruff check src tests
ruff format src tests

Type Checking

mypy src/canvas_tui

Tests

pytest -q
pytest --cov=canvas_tui

Git Workflow

Branches

• main — protected, production code
• feature/* — new features
• fix/* — bug fixes
• chore/* — maintenance

Commits

All commits to protected branches must be GPG signed.

git config commit.gpgsign true

Pull Requests

1. Create feature branch from main
2. Make changes and commit
3. Push to origin
4. Open PR
5. Ensure CI passes
6. Request review
7. Merge when approved

Adding a New Screen

1. Create file in src/canvas_tui/screens/
2. Inherit from Screen
3. Define compose() method
4. Add navigation in app.py
5. Add tests in tests/

Example:

from textual.app import ComposeResult
from textual.widgets import Static
from textual.screen import Screen

class MyScreen(Screen):
    def compose(self) -> ComposeResult:
        yield Static("My Screen")

Adding a New API Endpoint

1. Add method to api.py
2. Add corresponding model in models.py
3. Add cache support in cache.py
4. Add unit tests

Testing

Unit Tests

• Place in tests/ directory
• Use pytest fixtures
• Mock external API calls
• Aim for >80% coverage

Integration Tests

• Use Canvas sandbox if available
• Test offline cache behavior
• Verify error handling

Release Process

1. Merge PRs to main
2. CI automatically:
   • Runs tests
   • Builds package
   • Creates snapshot release
3. For stable releases, create a tag

Documentation

• Update README.md for user-facing changes
• Update docs-site/ for architecture changes
• Update wiki for workflow changes