# jlsilva01/projeto-ed-satc architecture

> Architecture diagram of the GitHub repository jlsilva01/projeto-ed-satc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jlsilva01/projeto-ed-satc
- Repository: https://github.com/jlsilva01/projeto-ed-satc

## Overview

##### Project type and purpose
- This is a data-engineering-oriented backend service implemented in Python, exposing a REST API via FastAPI/Uvicorn.
- It is packaged and delivered as a Docker container, orchestrated locally via Docker Compose, with production infrastructure provisioned via Terraform (IaC).
- It also includes auto-generated documentation (Swagger/ReDoc) and a static docs site built with MkDocs.

##### File structure
- Top-level directories:
- projeto_ed_satc/  – application package (FastAPI app code)
- docker/     – Docker Compose and container config
- iac/      – Terraform modules for cloud infra
- docs/      – MkDocs source for project documentation
- tests/      – unit and integration tests
- scripts/, examples/, assets/, data/ – helper scripts, sample data, and static assets
- Configuration files: pyproject.toml (build), mkdocs.yml, Dockerfiles (in docker/), Terraform files (iac/), pre-commit config in pyproject.toml.

##### Key insights from README
- Tech stack: Python 3.11+, FastAPI, Uvicorn, Docker, Docker Compose, Terraform, MkDocs.
- CI pipeline: GitHub Actions for lint & tests, image build & push to Docker Hub.
- Local workflow: “uv run uvicorn app.main:app --reload” and “uv run mkdocs serve”.
- Deployment: Docker Compose for local dev; Terraform for cloud.

##### Main components
a. Developer & SCM
- Developer workstation
- GitHub repository (source + CI workflows)
b. CI/CD pipeline
- GitHub Actions: lint, test, build Docker image, push to Docker Hub
c. Container registry
- Docker Hub (jlsilva01/projeto-ed-satc)
d. Infrastructure Provisioning
- Terraform (iac/) provisioning cloud resources (e.g., compute, network, storage)
e. Runtime environment
- Docker Compose (docker/) spinning up containers (FastAPI/Uvicorn) locally or on provisioned hosts
f. FastAPI application
- HTTP API endpoints
- Auto-generated Swagger UI / ReDoc
g. Data layer (if applicable)
- Local “data/” folder or external managed DB / object storage
h. Static documentation site
- MkDocs → GitHub Pages or hosted web server
i. Auxiliary components
- scripts/ for tooling
- examples/ for sample usage
- tests/ for validation

##### Relationships & data flows
- Developers → commit → GitHub repo
- GitHub Actions ← triggers on push/PR → runs tests → builds Docker image → pushes to Docker Hub
- Terraform (iac/) → provisions cloud infra (provider.tf → main.tf → outputs)
- Docker Compose (docker/) → pulls image from Docker Hub → deploys container on host
- Client (e.g., UI, CLI, external service) → HTTP request → FastAPI (Uvicorn) → processes → returns JSON
- FastAPI → reads/writes data from data layer (filesystem or external DB)
- MkDocs → reads docs/ → builds static site → deployed to GitHub Pages

##### Important architectural patterns & principles
- Containerization: isolates dependencies, ensures reproducible deployments
- Infrastructure as Code: Terraform for declarative infra provisioning
- Single-responsibility modules: Proyecto code (projeto_ed_satc/) vs. orchestration (docker/) vs. IaC (iac/) vs. docs (docs/)
- CI/CD: automated testing, linting, image building, and deployment
- Automated documentation: Swagger/ReDoc at runtime; MkDocs for static docs

##### Final checklist
- All major directories and their responsibilities are represented.
- CI/CD flow is explicit.
- Container registry and orchestration layers are distinct.
- Infrastructure provisioning step is included.
- Runtime service boundaries and data flows are clear.
- Static vs. dynamic documentation components are shown.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Development Zone
    subgraph "Development"
        Developer["Developer Workstation"]:::external
        GitHub["GitHub Repository"]:::code
    end
    Developer -->|commit code| GitHub

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        Actions["GitHub Actions"]:::pipeline
        Hub["Docker Hub"]:::external
    end
    GitHub -->|push triggers| Actions
    Actions -->|build & push image| Hub

    %% Infrastructure Provisioning
    subgraph "Infrastructure Provisioning"
        TF_provider["provider.tf"]:::infra
        TF_main["main.tf"]:::infra
        TF_vars["variables.tf"]:::infra
        TF_out["output.tf"]:::infra
    end
    Actions -->|apply infra| TF_main

    %% Runtime Environment
    subgraph "Runtime Environment"
        Compose["Docker Compose"]:::service
        FastAPI["FastAPI Service (Uvicorn)"]:::service
        Data["Local Data Layer (Filesystem)"]:::datastore
    end
    Hub -->|pull image| Compose
    Compose --> FastAPI
    FastAPI -->|read/write| Data

    %% Documentation
    subgraph "Documentation"
        MkSrc["docs/"]:::docs
        MkConfig["mkdocs.yml"]:::docs
        MkBuild["MkDocs Build (Static Site)"]:::docs
        Swagger["Swagger/ReDoc UI"]:::docs
    end
    MkSrc --> MkBuild
    MkConfig --> MkBuild
    FastAPI -->|auto-doc| Swagger
    MkBuild -->|deploy to GitHub Pages| GitHub

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        Tests["tests/"]:::aux
        Scripts["scripts/"]:::aux
        Examples["examples/"]:::aux
        Assets["assets/"]:::aux
        DataFolder["data/"]:::aux
        Config["pyproject.toml"]:::aux
    end
    GitHub --> Tests
    GitHub --> Scripts
    GitHub --> Examples
    GitHub --> Assets
    GitHub --> DataFolder
    GitHub --> Config

    %% Click Events
    click FastAPI "https://github.com/jlsilva01/projeto-ed-satc/tree/main/projeto_ed_satc/"
    click Compose "https://github.com/jlsilva01/projeto-ed-satc/tree/main/docker/"
    click TF_provider "https://github.com/jlsilva01/projeto-ed-satc/blob/main/iac/provider.tf"
    click TF_main "https://github.com/jlsilva01/projeto-ed-satc/blob/main/iac/main.tf"
    click TF_vars "https://github.com/jlsilva01/projeto-ed-satc/blob/main/iac/variables.tf"
    click TF_out "https://github.com/jlsilva01/projeto-ed-satc/blob/main/iac/output.tf"
    click MkConfig "https://github.com/jlsilva01/projeto-ed-satc/blob/main/mkdocs.yml"
    click MkSrc "https://github.com/jlsilva01/projeto-ed-satc/tree/main/docs/"
    click Tests "https://github.com/jlsilva01/projeto-ed-satc/tree/main/tests/"
    click Scripts "https://github.com/jlsilva01/projeto-ed-satc/tree/main/scripts/"
    click Examples "https://github.com/jlsilva01/projeto-ed-satc/tree/main/examples/"
    click Assets "https://github.com/jlsilva01/projeto-ed-satc/tree/main/assets/"
    click DataFolder "https://github.com/jlsilva01/projeto-ed-satc/tree/main/data/"
    click Config "https://github.com/jlsilva01/projeto-ed-satc/blob/main/pyproject.toml"

    %% Styles
    classDef service fill:#E3F2FD,stroke:#2196F3;
    classDef datastore fill:#E8F5E9,stroke:#4CAF50;
    classDef code fill:#FFF3E0,stroke:#FF9800;
    classDef pipeline fill:#F3E5F5,stroke:#9C27B0;
    classDef infra fill:#E1F5FE,stroke:#03A9F4;
    classDef docs fill:#FFFDE7,stroke:#FBC02D;
    classDef aux fill:#ECEFF1,stroke:#607D8B;
    classDef external fill:#FFEBEE,stroke:#F44336;
```
