Skip to content

Commit de9ec12

Browse files
matheusAFONSECAmatheusAFONSECA
committed
docs(ReadMe): Updating ReadMe
Updating Readme with description of the project, how to run and explanation of code.
1 parent 93ab98f commit de9ec12

File tree

1 file changed

+315
-2
lines changed

1 file changed

+315
-2
lines changed

‎README.md‎

Lines changed: 315 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,315 @@
1-
# to-do-list-backend
2-
Repository dedicated to store the backend's code of the To Do List project
1+
# To-Do List Backend (EN)
2+
3+
Repository dedicated to storing the **backend code** of the **To-Do List project**.
4+
5+
---
6+
7+
## Index
8+
9+
1. [Overview](#overview)
10+
2. [Requirements](#requirements)
11+
3. [Running Locally (Python)](#running-locally-python)
12+
4. [Running with Docker](#running-with-docker)
13+
5. [Project Architecture](#project-architecture)
14+
6. [MySQL Database](#mysql-database)
15+
7. [API Documentation](#api-documentation)
16+
8. [License](#license)
17+
18+
---
19+
20+
## Overview
21+
22+
The backend was developed in **Python 3.11** using the **FastAPI** framework and the **MySQL 8** database.
23+
It provides a **RESTful API** for task management (to-do list), organized by projects and associated with users authenticated via **JWT**.
24+
25+
---
26+
27+
## Requirements
28+
29+
- **Python 3.11**
30+
- **MySQL 8**
31+
- **Docker & Docker Compose** (optional)
32+
- `pip` (for dependency installation)
33+
34+
---
35+
36+
## Running Locally (Python)
37+
38+
1. Create and activate a virtual environment:
39+
```bash
40+
python -m venv venv
41+
source venv/bin/activate # Linux / Mac
42+
venv\Scripts\activate # Windows
43+
```
44+
45+
2. Install dependencies:
46+
```bash
47+
pip install -r requirements.txt
48+
```
49+
50+
3. Run the backend as a Python module:
51+
```bash
52+
python -m src.main
53+
```
54+
55+
4. Access:
56+
- API: [http://127.0.0.1:8000](http://127.0.0.1:8000)
57+
- Swagger Docs: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)
58+
59+
---
60+
61+
## Running with Docker
62+
63+
### Using Docker Compose
64+
65+
```bash
66+
docker compose -f docker/docker-compose.yaml -p todolist up --build
67+
```
68+
69+
**Access points:**
70+
- API → [http://localhost:8000](http://localhost:8000)
71+
- MySQL Database → `localhost:3307`
72+
73+
**Stop containers:**
74+
```bash
75+
docker compose -f docker/docker-compose.yaml -p todolist down
76+
```
77+
78+
**Restart environment and delete volumes (reset database):**
79+
```bash
80+
docker compose -f docker/docker-compose.yaml -p todolist down -v
81+
```
82+
83+
**Useful commands:**
84+
```bash
85+
docker compose -p todolist logs -f
86+
docker compose -p todolist restart api
87+
docker exec -it api-container bash
88+
docker exec -it todolist-mysql bash
89+
```
90+
91+
> Read more in [`docker_compose_documentation.md`](docs/en/docker_compose_documentation.md)
92+
93+
---
94+
95+
## Project Architecture
96+
97+
The project follows a **modular architecture** based on the **microservices pattern**, ensuring **scalability and maintainability**.
98+
99+
```
100+
src/
101+
├── main.py # Application entry point
102+
├── models/ # ORM models (SQLAlchemy)
103+
├── schemas/ # Pydantic schemas for validation
104+
├── routes/ # API endpoints
105+
├── modules/ # Database connections and helper modules
106+
├── utils/ # Utility functions
107+
└── database/ # SQL scripts (schema and seed)
108+
```
109+
110+
> Full details: [`api_project_architecture.md`](docs/en/api_project_architecture.md)
111+
112+
---
113+
114+
## MySQL Database
115+
116+
The database is configured via Docker and initialized automatically with schema and sample data.
117+
118+
**Image:** `mysql:8.0`
119+
**User:** `app`
120+
**Password:** `app_pass`
121+
**Database:** `todolist`
122+
**Local port:** `3307`
123+
124+
> Complete documentation: [`mysql_docker_documentation.md`](docs/en/mysql_docker_documentation.md)
125+
126+
---
127+
128+
## API and Docker
129+
130+
The API image is based on `python:3.11-slim`, configured to copy the project, install dependencies, and run the application.
131+
132+
> Read more: [`api_docker_documentation.md`](docs/en/api_docker_documentation.md)
133+
134+
---
135+
136+
## API Documentation
137+
138+
The API provides RESTful endpoints for managing users, projects, and tasks.
139+
140+
> Detailed endpoints: [`backend_proposal_todo_list.md`](docs/en/backend_proposal_todo_list.md)
141+
142+
---
143+
144+
## License
145+
146+
This project is under the **MIT License**.
147+
148+
---
149+
150+
> All additional documents can be found in the [`docs/en/`](./docs/en/) folder:
151+
> - [`api_project_architecture.md`](./docs/en/api_project_architecture.md)
152+
> - [`backend_proposal_todo_list.md`](./docs/en/backend_proposal_todo_list.md)
153+
> - [`api_docker_documentation.md`](./docs/en/api_docker_documentation.md)
154+
> - [`mysql_docker_documentation.md`](./docs/en/mysql_docker_documentation.md)
155+
> - [`docker_compose_documentation.md`](./docs/en/docker_compose_documentation.md)
156+
157+
158+
---
159+
160+
# To-Do List Backend (PT-BR)
161+
162+
Repositório dedicado ao armazenamento do código backend do **projeto To-Do List**.
163+
164+
---
165+
166+
## Index
167+
168+
1. [Visão Geral](#visão-geral)
169+
2. [Requisitos](#requisitos)
170+
3. [Como Executar Localmente (Python)](#como-executar-localmente-python)
171+
4. [Executando com Docker](#executando-com-docker)
172+
5. [Arquitetura do Projeto](#arquitetura-do-projeto)
173+
6. [Banco de Dados MySQL](#banco-de-dados-mysql)
174+
7. [Documentação da API](#documentação-da-api)
175+
8. [Licença](#licença)
176+
177+
---
178+
179+
## Visão Geral
180+
181+
O backend foi desenvolvido em **Python 3.11** utilizando o framework **FastAPI** e o banco de dados **MySQL 8**.
182+
O sistema fornece uma **API RESTful** para o gerenciamento de tarefas (to-do list), organizadas por projetos e associadas a usuários autenticados via **JWT**.
183+
184+
---
185+
186+
## Requisitos
187+
188+
- **Python 3.11**
189+
- **MySQL 8**
190+
- **Docker & Docker Compose** (opcional)
191+
- `pip` (para instalação de dependências)
192+
193+
---
194+
195+
## Como Executar Localmente (Python)
196+
197+
1. Crie e ative um ambiente virtual:
198+
```bash
199+
python -m venv venv
200+
source venv/bin/activate # Linux / Mac
201+
venv\Scripts\activate # Windows
202+
```
203+
204+
2. Instale as dependências:
205+
```bash
206+
pip install -r requirements.txt
207+
```
208+
209+
3. Execute o backend como módulo Python:
210+
```bash
211+
python -m src.main
212+
```
213+
214+
4. Acesse:
215+
- API: [http://127.0.0.1:8000](http://127.0.0.1:8000)
216+
- Swagger Docs: [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)
217+
218+
---
219+
220+
## Executando com Docker
221+
222+
### Usando Docker Compose
223+
224+
```bash
225+
docker compose -f docker/docker-compose.yaml -p todolist up --build
226+
```
227+
228+
**Acessos:**
229+
- API → [http://localhost:8000](http://localhost:8000)
230+
- Banco MySQL → `localhost:3307`
231+
232+
**Parar containers:**
233+
```bash
234+
docker compose -f docker/docker-compose.yaml -p todolist down
235+
```
236+
237+
**Reiniciar ambiente e apagar volumes (resetar banco):**
238+
```bash
239+
docker compose -f docker/docker-compose.yaml -p todolist down -v
240+
```
241+
242+
**Comandos úteis:**
243+
```bash
244+
docker compose -p todolist logs -f
245+
docker compose -p todolist restart api
246+
docker exec -it api-container bash
247+
docker exec -it todolist-mysql bash
248+
```
249+
250+
> Leia mais em [`docker_compose_documentation.md`](docs/pt-br/docker_compose_documentation.md)
251+
252+
---
253+
254+
## Arquitetura do Projeto
255+
256+
O projeto segue uma **arquitetura modular**, baseada no padrão de microsserviços, garantindo **escalabilidade e manutenibilidade**.
257+
258+
```
259+
src/
260+
├── main.py # Ponto de entrada da aplicação
261+
├── models/ # Modelos ORM (SQLAlchemy)
262+
├── schemas/ # Schemas Pydantic para validação
263+
├── routes/ # Endpoints da API
264+
├── modules/ # Conexão com banco e módulos auxiliares
265+
├── utils/ # Funções utilitárias
266+
└── database/ # Scripts SQL (schema e seed)
267+
```
268+
269+
> Detalhes completos: [`api_project_architecture.md`](docs/pt-br/api_project_architecture.md)
270+
271+
---
272+
273+
## Banco de Dados MySQL
274+
275+
O banco de dados é configurado via Docker e inicializado com schema e dados de exemplo automaticamente.
276+
277+
**Imagem:** `mysql:8.0`
278+
**Usuário:** `app`
279+
**Senha:** `app_pass`
280+
**Banco:** `todolist`
281+
**Porta local:** `3307`
282+
283+
> Documentação completa: [`mysql_docker_documentation.md`](docs/pt-br/mysql_docker_documentation.md)
284+
285+
---
286+
287+
## API e Docker
288+
289+
A imagem da API é baseada em `python:3.11-slim`, configurada para copiar o projeto, instalar dependências e executar:
290+
291+
292+
> Leia mais: [`api_docker_documentation.md`](docs/pt-br/api_docker_documentation.md)
293+
294+
---
295+
296+
## Documentação da API
297+
298+
A API fornece endpoints RESTful para gerenciamento de usuários, projetos e tarefas.
299+
300+
> Endpoints detalhados: [`backend_proposal_todo_list.md`](docs/pt-br/backend_proposal_todo_list.md)
301+
302+
---
303+
304+
## Licença
305+
306+
Este projeto está sob a **Licença MIT**.
307+
308+
---
309+
310+
> Todos os documentos adicionais encontram-se na pasta [`docs/pt-br/`](./docs/pt-br/).
311+
> - [`api_project_architecture.md`](./docs/pt-br/api_project_architecture.md)
312+
> - [`backend_proposal_todo_list.md`](./docs/pt-br/backend_proposal_todo_list.md)
313+
> - [`api_docker_documentation.md`](./docs/pt-br/api_docker_documentation.md)
314+
> - [`mysql_docker_documentation.md`](./docs/pt-br/mysql_docker_documentation.md)
315+
> - [`docker_compose_documentation.md`](./docs/pt-br/docker_compose_documentation.md)

0 commit comments

Comments
 (0)