Architecture

Chapter 1: Understanding how sparQ works under the hood.

Now that you've built your first app, let's step back and understand how sparQ is structured. This knowledge will help you make better decisions as you build more complex applications.

Design Philosophy

sparQ is built on a foundation that prioritizes modularity and extensibility. The goal is a system that can grow and scale over time while remaining simple, intuitive, and efficient.

Everything in sparQ—including the core system itself—is a module. This means:

• Consistency - Once you understand one module, you understand them all
• Isolation - Modules don't interfere with each other
• Extensibility - Add functionality without touching core code
• Simplicity - Each module does one thing well

Architectural Principles

Seven key pillars guide sparQ's architecture:

The Big Picture

sparQ is a modular business platform built on Flask. Think of it as a foundation that handles all the common stuff—authentication, database, email, payments—so you can focus on building your specific business logic.

Here's what makes up a sparQ installation:

+-------------------------------------------------------------+
|                      Flask Application                      |
|                         (app.py)                            |
+-------------------------------------------------------------+
|                                                             |
|  +-----------+  +-----------+  +---------------------+      |
|  |  Module   |  | Database  |  |        i18n         |      |
|  |  Loader   |  |(SQLAlchemy)|  |   (JSON files)     |      |
|  | (pluggy)  |  |  SQLite   |  |                     |      |
|  +-----+-----+  +-----------+  +---------------------+      |
|        |                                                    |
|        v                                                    |
|  +-----------------------------------------------------+    |
|  |                    Modules                          |    |
|  |  +-------+ +-------+ +-------+ +-------+            |    |
|  |  | Core  | | Team  | |Dashbrd| | Apps  |            |    |
|  |  +-------+ +-------+ +-------+ +-------+            |    |
|  +-----------------------------------------------------+    |
|                                                             |
+-------------------------------------------------------------+

Required Modules

Three modules are essential for sparQ to run:

Everything else—Sales, Billing, Service, and your custom apps—is optional and loads only when needed.

Technology Stack

sparQ uses a carefully chosen set of technologies:

System Services

sparQ provides a set of system services that any module can use. These live in the system/ directory:

You'll use these services throughout your apps. For example, to require login on a route:

from system.auth import login_required

@bp.route('/dashboard')
@login_required
def dashboard():
    return render_template('my_app/dashboard.html')

Request Lifecycle

When a user clicks something in your app, here's what happens:

1. Request arrives at Flask
       ↓
2. URL routing matches a controller
       ↓
3. Auth middleware checks permissions
       ↓
4. Your controller runs
       ↓
5. Controller calls models/services
       ↓
6. Template renders HTML
       ↓
7. Response sent to browser

Let's trace a real example. When a user visits /hello/ from your Hello sparQ app:

1. Flask sees the URL matches @bp.route('/') in your main.py controller
2. Your index() function runs
3. It calls render_template('hello/desktop/index.html')
4. Jinja2 processes the template
5. HTML is sent back to the browser

The Frontend Stack

sparQ uses a server-rendered approach rather than a Single Page Application (SPA). This means:

• Jinja2 - Templates render HTML on the server
• HTMX - Makes pages feel dynamic without writing JavaScript
• Alpine.js - Handles small UI interactions (dropdowns, modals)
• Bootstrap 5 - Provides the CSS framework

This stack is simpler than React/Vue and perfect for business applications where SEO matters and you don't need complex client-side state.

Database Layer

sparQ uses SQLite as its primary database and SQLAlchemy as its ORM (Object-Relational Mapper). This lets you work with Python objects instead of writing raw SQL:

# Instead of: SELECT * FROM tasks WHERE user_id = 1
tasks = Task.query.filter_by(user_id=1).all()

# Instead of: INSERT INTO tasks (title, user_id) VALUES ('Buy milk', 1)
task = Task(title='Buy milk', user_id=1)
db.session.add(task)
db.session.commit()

SQLite might seem simple, but it's incredibly capable. It handles millions of records, supports concurrent reads, and requires zero configuration. For most business applications, it's more than enough.

The SDK

The sdk/ folder contains developer tooling for building apps:

# Create a new app with auto-generated mappid
cd sdk
make app name=myapp

# Package for marketplace
make release name=myapp

The SDK handles scaffolding, generates unique marketplace IDs (mappid), and packages apps for distribution.

The Module System

Everything in sparQ is a module. There are three types:

When sparQ starts, it automatically discovers and loads modules in this order:

1. Core - Authentication, base templates
2. Dashboard - Business dashboard (Home)
3. Team - Employee management
4. Other base modules - Alphabetically
5. Your apps - Alphabetically

Modules can define dependencies on other modules, ensuring they load in the correct order.

We'll dive deeper into modules in the next chapter.

Key Takeaways

• sparQ prioritizes modularity—everything is a self-contained module
• Core, Dashboard, and Team modules are required; everything else is optional
• Flask + SQLite + SQLAlchemy provide the foundation
• Server-rendered HTML with HTMX gives you dynamic UIs without JavaScript complexity
• System services (auth, db, email, etc.) are available to all modules
• Modules are automatically discovered and loaded at startup