> ## Documentation Index
> Fetch the complete documentation index at: https://docs.a7manager.se/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

## High-level system description

A Django REST backend with PostgreSQL, with two clients: the main React web application and
a separate offline-first PWA used by inspectors in the field. Bulk data arrives through an
ingestion pipeline that writes to the database on its own validated path.

```mermaid theme={null}
flowchart LR
    subgraph Users
        A[Web application<br/>desktop browser]
        B[Inspector app<br/>phone or tablet]
    end
    subgraph Platform
        C[Backend<br/>rules and API]
        D[(Database)]
    end
    subgraph Sources
        E[Daily CSV exports<br/>from other systems]
        F[Import pipeline]
    end

    A --> C
    B --> C
    C --> D
    E --> F --> D
```

## Domain layers

Internally the backend is organised in layers of Django applications. Dependencies
generally point downward: a higher layer uses what is below it, and the layers below do not
depend on the modules above.

<Steps>
  <Step title="Foundation">
    **Users, projects, and shared plumbing.** Who can log in, which fleets they have access
    to, and the conventions every other part of the system follows. Always present, never
    visible as a feature in its own right.

    `authentication` · `user` · `projects` · `common`
  </Step>

  <Step title="Fleet registry">
    **The assets.** Vehicle types, the standardised product-group hierarchy, component
    types, mounting positions, and then the actual vehicles and components in service.
    This is the backbone — nearly everything else attaches to a vehicle or a component.

    `assets`
  </Step>

  <Step title="Modules">
    **The working areas.** Each adds records that point back at the fleet registry beneath
    it.

    `servicebook` · `defects` · `warranty` · `measurements` · `planner` · `inspections` ·
    `high_value_components` · `strategic_kpi` · `askai`
  </Step>
</Steps>

The modules are not independent of each other. `defects` builds on `servicebook`, `warranty`
and `strategic_kpi` build on `defects`, and `askai` reads across most of the others.

<Note>
  The downward rule holds for module-level imports but is not absolute. `common` reaches up
  into `assets` and `inspections` in a few places, using function-local imports to avoid
  circular-import errors at load time.
</Note>

## Navigation structure

The **Pages** tab follows the application's own sidebar. What a user sees
depends on their assigned roles.

| Sidebar section    | Pages                                                                                                                                                                                               | Requires                                             |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| —                  | [Ask AI](/pages/ask-ai)                                                                                                                                                                             | AI Analytics User                                    |
| **Assets**         | [Vehicles](/pages/vehicles), [Components](/pages/components)                                                                                                                                        | Asset Manager                                        |
| **Strategic KPI**  | [Strategic KPI](/pages/strategic-kpi)                                                                                                                                                               | Asset Manager                                        |
| **Service Book**   | [Defects](/pages/defects), [Maintenance Records](/pages/maintenance-records), [Maintenance Status](/pages/maintenance-status), [Out of Service](/pages/out-of-service), [Cleaning](/pages/cleaning) | Asset Manager                                        |
| **Planning**       | [Maintenance Planner](/pages/planner)                                                                                                                                                               | Planner or Asset Manager                             |
| **Wheel**          | [Wheel Analysis](/pages/wheel-analysis)                                                                                                                                                             | Asset Manager                                        |
| **Warranty**       | [Warranty](/pages/warranty)                                                                                                                                                                         | Warranty Manager, Warranty Supplier or Asset Manager |
| **Inspections**    | [Inspections](/pages/inspections)                                                                                                                                                                   | Inspection Manager, Inspector or Asset Manager       |
| **HVC**            | [HVC Management](/pages/high-value-components)                                                                                                                                                      | Component Manager or Asset Manager                   |
| **Project Config** | [Vehicle Types](/pages/vehicle-types), [Component Types](/pages/component-types), [Maintenance Plan](/pages/maintenance-plans), [Measurements](/pages/measurement-config)                           | Asset Manager                                        |
| **Admin**          | [Users, Projects](/pages/admin)                                                                                                                                                                     | Superuser                                            |

Field inspections happen in a separate [inspector app](/pages/inspector-app) rather than in
the web application.

## Data origin

Data can enter the platform in three distinct ways.

<AccordionGroup>
  <Accordion title="Configured in the application">
    The definitions admin sets up: vehicle
    types, the product-group hierarchy, component types, mounting positions, measurement
    types and their thresholds, inspection templates. Created and edited in the web
    application.
  </Accordion>

  <Accordion title="Created by people using the platform">
    The work the platform is actually for: warranty claims and their approval history,
    component repair-loop updates, inspection findings, maintenance plannings, comments and
    attachments. Created through the web application or the inspector app.
  </Accordion>

  <Accordion title="Imported from CSV files">
    The daily operational record: defects, odometer readings, mount and dismount events,
    performed maintenance, measurements, out-of-service periods, cleaning. These arrive as
    CSV exports from other systems and are **read-only inside the platform** — they cannot
    be edited in the application, because the next import would overwrite the change.
  </Accordion>
</AccordionGroup>

[Database structure](/data/schema-overview) explains the data structure in details, and
the file format pages describe exactly what each csv file must contain.

## Environments

Production runs in its own Azure subscription, behind an Application Gateway
WAF with the application tier network-isolated and the database reachable only over a
private endpoint. A separate development environment is public and holds test
data only.

See [Environments](/platform/environments) for the topology, security posture, recovery
guarantees, and what an integrating system needs from each.