# Architecture and Styling Reference

## Project Boundaries

Use this dependency direction:

- pages import components and services
- components contain presentation logic only
- services contain business logic and do not import UI
- static assets are mounted and loaded once at bootstrap

Suggested module split:

```text
src/app/
  ui/pages/
  ui/components/
  ui/static/
  services/
  api/
  bootstrap.py
```

## Component Extraction Rules

Extract to ui/components when a pattern appears in two or more pages.

Keep in-page if the layout is specific to a single route.

```python
def card_section(title: str, content: str) -> ui.card:
    with ui.card().classes("w-full max-w-md") as card:
        ui.label(title).classes("text-lg font-bold")
        ui.label(content).classes("text-gray-600")
    return card
```

## Tailwind-First Layout Pattern

Use Tailwind utility classes for structure and spacing.
Use breakpoint classes for responsive behavior.
Use .style() only for values that must be computed dynamically.

```python
with ui.column().classes("w-full"):
    with ui.row().classes("w-full gap-4 flex-wrap sm:flex-nowrap"):
        ui.card().classes("flex-1 min-w-64")
        ui.card().classes("flex-1 min-w-64")
```

## Styling Decision Order

1. Tailwind utility classes
2. Quasar props
3. Reusable styled component functions
4. Minimal custom CSS loaded once at bootstrap (only when needed)

```python
from fastapi.staticfiles import StaticFiles

app.mount("/static", StaticFiles(directory="src/app/static"), name="static")
ui.add_css(open("src/app/static/css/base.css").read())
```

## Static Asset Rules

- Keep custom CSS small and tokenized with variables.
- Avoid per-page CSS injection.
- Verify static mount paths and reverse proxy rewrites.

## Links

!!! info "Primary sources"
    - [NiceGUI elements](https://nicegui.io/documentation/element)
    - [NiceGUI binding properties](https://nicegui.io/documentation/section_binding_properties)
    - [Tailwind utility-first styling](https://tailwindcss.com/docs/utility-first)
    - [Quasar components](https://quasar.dev/vue-components)