# Documentation Index

This folder contains guides for the REST Sun Grass backend.

## Guides

| Guide | What it covers |
|-------|---------------|
| [Architecture](./architecture.md) | System context, backend structure, execution model, workflow sequence, and storage boundaries |
| [Setup](./setup.md) | Installation, Docker Compose, `.env` configuration, first login smoke-test |
| [Authentication](./authentication.md) | Login flow, token/session lifecycle, session concepts, and user management endpoints |
| [Terrain and Solar Radiation](./terrain_and_solar_radiation.md) | Real and synthetic DSM paths, slope/aspect, horizon analysis, `r.sun`, and required workflow order |
| [Simulation Inputs](./simulation_inputs.md) | Parquet artifact pipeline, suitable-area modes, weather preparation, and canonical output layout |
| [Simulation Models](./simulation_models.md) | Real-sky batch simulation, fast horizon-based simulation, and co-simulation, including required inputs, model parameters, and output schemas |

## Recommended Reading Order

If you are new to the system, read the guides in this order:

1. [Architecture](./architecture.md) — understand the overall system
2. [Setup](./setup.md) — get the system running on your machine
3. [Authentication](./authentication.md) — log in and manage sessions and users
4. [Terrain and Solar Radiation](./terrain_and_solar_radiation.md) — prepare terrain inputs and run `r.sun`
5. [Simulation Inputs](./simulation_inputs.md) — generate parquet artifacts and prepare weather data
6. [Simulation Models](./simulation_models.md) — run batch or co-simulation

## Workflow Map

```mermaid
flowchart TD
    A[Auth & session] --> B[Terrain acquisition]
    B --> C[Terrain products and r.sun]
    C --> D[Parquet artifacts]
    D --> E[Weather preparation]
    E --> F[Batch simulation]
    E --> G[Fast horizon simulation]
    D --> H[Co-simulation CLI]
```

## Notes

- Solar API routes are exposed under the `/solar` prefix.
- Authentication routes are exposed under `/auth`.
- User management routes are exposed under `/users`.
- Interactive API docs are available in Swagger at `/docs`.
