How jlsilva01/projeto-ed-satc works
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.