Feat/documentacoes (#78)

* readme principal

* doc para app de database

* doc para app de proxy

* Update README.md

* doc identidades

* doc modulo pesquisa

README.md

@@ -1,3 +1,98 @@
-# Pescarte
+# PEA Pescarte
 
-**TODO: Add description**
+[![lint](https://github.com/peapescarte/pescarte-api/actions/workflows/lint.yml/badge.svg)](https://github.com/peapescarte/pescarte-api/actions/workflows/lint.yml)
+[![test](https://github.com/peapescarte/pescarte-api/actions/workflows/test.yml/badge.svg)](https://github.com/peapescarte/pescarte-api/actions/workflows/test.yml)
+
+------------------------------------------------------------------------
+
+## Setup Ambiente de desenvolvimento
+
+### Primeira vez rodando
+
+Este projeto possui três opções para ambientes de desenvolvimento:
+
+1.  [Docker](./guides/local/docker.md)
+2.  [Nix](./guides/local/nix.md)
+3.  [asdf](./guides/local/asdf.md)
+
+## Estrutura do projeto
+
+O projeto **PEA Pescarte** está implementado como uma aplicação [umbrella](https://elixirschool.com/pt/lessons/advanced/umbrella_projects). Isso significa que o projeto pode ser entendido como disposto no padrão [monorepo](https://pt.stackoverflow.com/questions/452607/o-que-%C3%A9-um-monorepo-quais-s%C3%A3o-as-suas-vantagens-e-desvantagens).
+
+Em suma, o projeto é dividido entre algumas aplicações internas, com responsabilidades diferentes e bem definidas. Siga a tabela abaixo para entender cada app interno e suas responsabilidades:
+
+- [Database](./apps/database)
+- [Proxy web](./apps/proxy_web)
+- [Identidades](./apps/identidades)
+- [Módulo Pesquisa](./apps/modulo_pesquisa)
+- [Plataforma Digital](./apps/plataforma_digital)
+- [API Plataforma Digital](./apps/plataforma_digital_api)
+
+------------------------------------------------------------------------
+
+## Guias
+
+-   [Testes](./guides/tests.md)
+-   [Testes de integração](./guides/integration_tests.md)
+
+## Por que usar Elixir?
+
+<a id="why-elixir" />
+
+[Elixir][ elixir-site ] é uma [linguagem funcional][ functional-prog ], criada em 2011 pelo José Valim. Ela é baseada na [BEAM][ beam-meaning ], a máquina virtual do [Erlang][ erlang-meaning ]. O Erlang é conhecido por ser uma linguagem robusta, perfeita para aplicações que necessitam ser tolerantes à falhas, concorrentes - aproveitando todo o potencial da máquina - e escaláveis.
+
+O [Elixir][ elixir-site ] surgiu com a proprosta de modernizar a sintaxe do [Erlang][ erlang-meaning ], que é fortemente herdada de [Prolog][ prolog-meaning ] - uma linguagem do paradigma lógico - e adicionar um gerenciador de depêndencias. Elixir e Erlang não são linguagens funcionais porque querem ser, e sim pois a concorrência e paralelismo num programa [POO][ oop-meaning ], [mutável][ immutability ] e [imperativo][ imperative-prog ], torna o gerenciamento das [threads][ thread-meaning ] algo que beira o impossível.
+
+Vantagens da programação funcional:
+
+- Imutabilidade
+- Melhor testabilidade
+- Programação declarativa
+- Sintaxe mais humanamente amigável
+- Funções puras, sem efeitos colaterais
+
+### Diferença entre Concorrência e Paralelismo em Computação
+
+<a id="concurrency-parallelism" />
+
+Imagine uma máquina de venda de refrigerantes, onde apenas uma lata sai por vez, ou seja, apenas uma pessoa pode ser "atendida" após a outra. Com o tempo, forma-se uma fila para comprar refrigerante, onde cada pessoa retira seu item e vai embora. Neste caso, temos um modelo de programação linear.
+
+Fazendo a correlação deste cenário onde a máquina de refrigerante representa a [CPU][ cpu-meaning ] do computador e a fila de pessoas representa a fila de [processos](<https://pt.wikipedia.org/wiki/Processo_(inform%C3%A1tica)>) os quais essa CPU executa.
+
+Agora imagine que temos 2 (duas) máquinas de refrigerante - ou seja, duas CPUs, ou de forma mais realista, dois [núcleos](https://canaltech.com.br/hardware/como-ativar-os-nucleos-do-processador/) dentro da CPU - e agora cada máquina de refrigerante possui sua própria fila de pessoas - processos da CPU. Neste caso, chamamos esse modelo de computação de [_Paralelismo_][ paralel-meaning ].
+
+Num último caso, imagine que existe apenas 1 (uma) máquina de refrigerante (CPU) porém essa máquina é capaz de atender múltiplas filas de pessoas (processos), ou seja, mais de uma pessoa pode retirar seu item ao mesmo tempo da máquina. Para esse modelo de computação damos o nome de [_Concorrência_][ concurrency-meaning ].
+
+A imagem a seguir exemplifica os conceitos de _Paralelismo_ e _Concorrência_:
+
+<p align="center">
+ <img src="https://user-images.githubusercontent.com/44469426/230241225-60c9ac79-302d-4a19-96bd-b76585c5b902.png" />
+</p>
+
+### BEAM - máquina virtual do Erlang
+
+<a id="beam" />
+
+A [BEAM][ beam-meaning ] é a máquina virtual do [Erlang][ erlang-meaning ] (assim como a [JVM][ jvm-meaning ] do [JAVA][ java-meaning ]). Seu funcionamento básico é: ela divide cada ação do seu programa em pequenas ações, chamados de processos (não confundir com os processos do sistema operacional da máquina local). Esses processos são supervisionados pela própria BEAM, para que quando haja algum erro, o sistema se recupere sozinho e sem atrapalhar os outros processos.
+
+Quando uma aplição Elixir/Erlang é iniciada, a BEAM cria um "Agendador" (Scheduler) para cada núcleo da CPU da máquina. Esses Agendadores também são processos, mas que supervisionam, agendam e gerenciam os outros processos da aplicação. A imagem a seguir exemplifica a crição dos Agendadores:
+
+<p align="center">
+  <img src="https://user-images.githubusercontent.com/44469426/230241258-08aeb6d8-9038-4eda-89f0-fb13de077aa9.png" />
+</p>
+
+[beam-meaning]: https://www.erlang.org/blog/a-brief-beam-primer/
+[erlang-meaning]: https://coodesh.com/blog/dicionario/o-que-e-erlang/
+[immutability]: https://medium.com/opensanca/imutabilidade-eis-a-quest%C3%A3o-507fde8c6686
+[imperative-prog]: https://pt.wikipedia.org/wiki/Programa%C3%A7%C3%A3o_imperativa
+[functional-prog]: https://pt.wikipedia.org/wiki/Programa%C3%A7%C3%A3o_funcional
+[java-meaning]: https://www.java.com/pt-BR/download/help/whatis_java.html
+[jvm-meaning]: https://pt.wikipedia.org/wiki/M%C3%A1quina_virtual_Java
+[prolog-meaning]: https://ww2.inf.ufg.br/~eduardo/lp/alunos/prolog/prolog.html
+[thread-meaning]: https://pt.wikipedia.org/wiki/Thread_(computa%C3%A7%C3%A3o)
+[oop-meaning]: https://www.alura.com.br/artigos/poo-programacao-orientada-a-objetos
+[process-meaning]: https://pt.wikipedia.org/wiki/Processo_(inform%C3%A1tica)
+[cpu-meaning]: https://pt.wikipedia.org/wiki/Unidade_central_de_processamento
+[paralel-meaning]: https://pt.wikipedia.org/wiki/Computa%C3%A7%C3%A3o_paralela
+[concurrency-meaning]: (https://pt.wikipedia.org/wiki/Programa%C3%A7%C3%A3o_concorrente)
+[elixir-site]: https://elixir-lang.org

apps/database/README.md

@@ -1,3 +1,46 @@
 # Database
 
-**TODO: Add description**
+Aplicação responsável por gerenciar as conexões com o banco de dados.
+
+Atualmente existem dois tipos de conexão:
+
+1. Escrita: Usada para ações de inserção, atualização ou remoção
+2. Leitura: Usada apenas para consultas
+
+## Como usar
+
+Após criar uma nova aplicação com `mix new <nome-app>`, adicione este app como dependência:
+
+```elixir
+  defp deps do
+    [
+      {:database, in_umbrella: true}
+    ]
+  end
+```
+
+Agora é possivel definit modelos e módulo de repositorio:
+
+```elixir
+defmodule MeuApp.Models.MeuModelo do
+  use Database, :model
+
+  # ...
+end
+```
+
+```elixir
+defmodule MeuApp.Repository do
+  use Database, :repository
+
+  # ...
+end
+```
+
+Em adição as definições, também foram definidas funções para facilitar o casamento de padrões (pattern matching) no retorno delas:
+
+```elixir
+Database.fetch(read_repo(), MeuModelo, chave_primaria)
+Database.fetch_one(read_repo(), query)
+Database.fetch_by(read_repo(), MeuModelo, coluna)
+```

apps/identidades/README.md

@@ -1,3 +1,59 @@
 # Identidades
 
-**TODO: Add description**
+Aplicação responsável pelo cadastro e gerenciamento de pessoas usuárias e dados pessoais. Também tem responsabilidade de gerenciar tokens de usuário, usados para criar sessões web, por exemplo.
+
+A aplicação respeita a arquitetura explícita, onde temos:
+
+1. `handlers/`
+2. `models/`
+3. `repository.ex`
+4. `services/`
+
+## Handlers
+
+Basicamente são controllers, que expõe uma API pública do contexto/app para que outras aplicações possam usar! Cada `handler` deve respeitar um [comportamento/interface](https://elixirschool.com/pt/lessons/advanced/behaviours) e se restringir a um sub-domínio da aplicação.
+
+### CredenciaisHandler
+
+Código fonte pode ser visto [aqui](./lib/identidades/handlers/credenciais_handler.ex)
+
+```elixir
+CredenciaisHandler.confirm_usuario/2
+CredenciaisHandler.delete_session_token/1
+CredenciaisHandler.fetch_usuario_by_reset_password_token/1
+CredenciaisHandler.fetch_usuario_by_session_token/2
+CredenciaisHandler.generate_email_token/2
+CredenciaisHandler.generate_session_token/1
+CredenciaisHandler.update_usuario_password/3
+CredenciaisHandler.reset_usuario_password/2
+```
+
+### UsuarioHandler
+
+Código fonte pode ser visto [aqui](./lib/identidades/handlers/usuario_handler.ex)
+
+```elixir
+UsuarioHandler.create_usuario_admin/1
+UsuarioHandler.create_usuario_pesquisador/1
+UsuarioHandler.fetch_usuario_by_id_publico/1
+UsuarioHandler.fetch_usuario_by_cpf_and_password/2
+UsuarioHandler.fetch_usuario_by_email_and_password/2
+UsuarioHandler.list_usuario/0
+```
+
+## Models
+
+São definidos os  modelos/entidades da aplicação, e devem ser a fonte da verdade do contexto. Podem representar tabelas de um banco de dados ou entidades mais abstratas.
+
+- [Contato](./lib/identidades/models/contato.ex)
+- [Endereço](./lib/identidades/models/endereco.ex)
+- [Token](./lib/identidades/models/token.ex)
+- [Usuário](./lib/identidades/models/usuario.ex)
+
+## Repository
+
+Arquivo responsável por definir funções que interagem diretamente com o banco de dados, como inserção ou consultas.
+
+## Services
+
+Casos de uso, onde se concentram arquivos de lógica de negócio. Podem modificar entidades e são constituidos apenas por funções puras.

apps/modulo_pesquisa/README.md

@@ -1 +1,60 @@
 # Modulo Pesquisa
+
+Aplicação responsável pelo cadastro e gerenciamento da parte administrativa da plataforma PEA Pescarte.
+
+A aplicação respeita a arquitetura explícita, onde temos:
+
+1. `handlers/`
+2. `models/`
+3. `repository.ex`
+4. `services/`
+
+## Handlers
+
+Basicamente são controllers, que expõe uma API pública do contexto/app para que outras aplicações possam usar! Cada `handler` deve respeitar um [comportamento/interface](https://elixirschool.com/pt/lessons/advanced/behaviours) e se restringir a um sub-domínio da aplicação.
+
+### MidiasHandler
+
+Código fonte pode ser visto [aqui](./lib/modulo_pesquisa/handlers/midias_handler.ex)
+
+```elixir
+MidiasHandler.create_categoria/1
+MidiasHandler.create_midia/1
+MidiasHandler.create_midia_and_tags/2
+MidiasHandler.create_tag/1
+MidiasHandler.create_multiple_tags/2
+MidiasHandler.fetch_categoria/1
+MidiasHandler.fetch_midia/1
+MidiasHandler.list_categoria/0
+MidiasHandler.list_midia/0
+MidiasHandler.list_midias_from_tag/1
+MidiasHandler.list_tag/0
+MidiasHandler.list_tags_from_categoria/1
+MidiasHandler.list_tags_from_midia/1
+MidiasHandler.remove_tags_from_midia/2
+MidiasHandler.update_midia/1
+MidiasHandler.update_tag/1
+```
+
+## Models
+
+São definidos os  modelos/entidades da aplicação, e devem ser a fonte da verdade do contexto. Podem representar tabelas de um banco de dados ou entidades mais abstratas.
+
+- [Campus](./lib/modulo_pesquisa/models/campus.ex)
+- [Linha Pesquisa](./lib/modulo_pesquisa/models/linha_pesquisa.ex)
+- [Midia](./lib/modulo_pesquisa/models/midia.ex)
+  - [Categoria](./lib/modulo_pesquisa/models/midia/categoria.ex)
+  - [Tag](./lib/modulo_pesquisa/models/midia/tag.ex)
+- [Nucleo Pesquisa](./lib/modulo_pesquisa/models/nucleo_pesquisa.ex)
+- [Pesquisador](./lib/modulo_pesquisa/models/pesquisador.ex)
+- [Relatorio Anual Pesquisa](./lib/modulo_pesquisa/models/relatorio_anual_pesquisa.ex)
+- [Relatorio Mensal Pesquisa](./lib/modulo_pesquisa/models/relatorio_mensal_pesquisa.ex)
+- [Relatorio Trimestral Pesquisa](./lib/modulo_pesquisa/models/relatorio_trimestral_pesquisa.ex)
+
+## Repository
+
+Arquivo responsável por definir funções que interagem diretamente com o banco de dados, como inserção ou consultas.
+
+## Services
+
+Casos de uso, onde se concentram arquivos de lógica de negócio. Podem modificar entidades e são constituidos apenas por funções puras.

apps/proxy_web/README.md

@@ -0,0 +1,14 @@
+# Proxy Web
+
+Uma aplicação para redirecionar requisições web para diferentes aplicações internas. Dessa forma é possível subir apenas um servidor web, que responde em diferentes rotas ou domínios, de forma prática e escalável.
+
+## Como usar
+
+Para subir o servidor web, basta executar `mix phx.server` dentro da raiz do projeto Pescarte, ou caso queira uma REPL interativo: `iex -S mix phx.server`.
+
+Caso seja necessário definir uma nova aplicação que irá receber requisições web, vá para o arquivo de [Endpoint](./lib/proxy_web/endpoint.ex), adicione sua aplicação no mapa de redirecionamento.
+Após essa adição, vá para o arquivo de [Router](./lib/proxy_web/plugs/router.ex) e defina a lógica necessária para o redirecionamento das requisições.
+
+Atualmente o redirecionamento ocorre com base no caminho de rotas das chamadas. Essa lógica pode ser modificada ou extendida caso necessária. Dessa forma, atualmente existem duas aplicações que recebem o redirecionamento:
+1. [Plataforma Digital](../plataforma_digital): Recebe toda requisição, por padrão.
+2. [API Plataforma Digital](../plataforma_digital_api): Recebe requisições a partir do caminho de rota `/api`.