Modular-monolith-refactoring

.env

@@ -18,25 +18,25 @@ STACK_NAME=full-stack-fastapi-project
 
 # Backend
 BACKEND_CORS_ORIGINS="http://localhost,http://localhost:5173,https://localhost,https://localhost:5173,http://localhost.tiangolo.com"
-SECRET_KEY=changethis
+SECRET_KEY=a8c2d9f3e7b6a5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f
 [email protected]
-FIRST_SUPERUSER_PASSWORD=changethis
+FIRST_SUPERUSER_PASSWORD=SecureAdminPass123!
 
 # Emails
-SMTP_HOST=
+SMTP_HOST=mailhog
 SMTP_USER=
 SMTP_PASSWORD=
 [email protected]
-SMTP_TLS=True
+SMTP_TLS=False
 SMTP_SSL=False
-SMTP_PORT=587
+SMTP_PORT=1025
 
 # Postgres
-POSTGRES_SERVER=localhost
+POSTGRES_SERVER=db
 POSTGRES_PORT=5432
 POSTGRES_DB=app
 POSTGRES_USER=postgres
-POSTGRES_PASSWORD=changethis
+POSTGRES_PASSWORD=SecureDbPass456!
 
 SENTRY_DSN=
 

.gitignore

@@ -3,4 +3,4 @@ node_modules/
 /test-results/
 /playwright-report/
 /blob-report/
-/playwright/.cache/
+/playwright/.cache/

README.md

@@ -24,6 +24,17 @@
 - 🚢 Deployment instructions using Docker Compose, including how to set up a frontend Traefik proxy to handle automatic HTTPS certificates.
 - 🏭 CI (continuous integration) and CD (continuous deployment) based on GitHub Actions.
 
+## Documentation
+
+For comprehensive documentation on how to use, develop, and extend this template, see the [documentation](./docs/README.md).
+
+Key documentation sections:
+
+- [Getting Started](./docs/01-getting-started/01-prerequisites.md) - Prerequisites and initial setup
+- [Architecture Overview](./docs/02-architecture/01-overview.md) - Modular monolith architecture design
+- [Development Workflow](./docs/03-development-workflow/) - Day-to-day development guidelines
+- [Extending the API](./docs/04-guides/01-extending-the-api.md) - How to add new modules and features
+
 ### Dashboard Login
 
 [![API docs](img/login.png)](https://github.com/fastapi/full-stack-fastapi-template)
@@ -138,7 +149,7 @@ Before deploying it, make sure you change at least the values for:
 
 You can (and should) pass these as environment variables from secrets.
 
-Read the [deployment.md](./deployment.md) docs for more details.
+Read the [deployment documentation](./docs/06-deployment/README.md) for more details.
 
 ### Generate Secret Keys
 
@@ -152,88 +163,6 @@ python -c "import secrets; print(secrets.token_urlsafe(32))"
 
 Copy the content and use that as password / secret key. And run that again to generate another secure key.
 
-## How To Use It - Alternative With Copier
-
-This repository also supports generating a new project using [Copier](https://copier.readthedocs.io).
-
-It will copy all the files, ask you configuration questions, and update the `.env` files with your answers.
-
-### Install Copier
-
-You can install Copier with:
-
-```bash
-pip install copier
-```
-
-Or better, if you have [`pipx`](https://pipx.pypa.io/), you can run it with:
-
-```bash
-pipx install copier
-```
-
-**Note**: If you have `pipx`, installing copier is optional, you could run it directly.
-
-### Generate a Project With Copier
-
-Decide a name for your new project's directory, you will use it below. For example, `my-awesome-project`.
-
-Go to the directory that will be the parent of your project, and run the command with your project's name:
-
-```bash
-copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust
-```
-
-If you have `pipx` and you didn't install `copier`, you can run it directly:
-
-```bash
-pipx run copier copy https://github.com/fastapi/full-stack-fastapi-template my-awesome-project --trust
-```
-
-**Note** the `--trust` option is necessary to be able to execute a [post-creation script](https://github.com/fastapi/full-stack-fastapi-template/blob/master/.copier/update_dotenv.py) that updates your `.env` files.
-
-### Input Variables
-
-Copier will ask you for some data, you might want to have at hand before generating the project.
-
-But don't worry, you can just update any of that in the `.env` files afterwards.
-
-The input variables, with their default values (some auto generated) are:
-
-- `project_name`: (default: `"FastAPI Project"`) The name of the project, shown to API users (in .env).
-- `stack_name`: (default: `"fastapi-project"`) The name of the stack used for Docker Compose labels and project name (no spaces, no periods) (in .env).
-- `secret_key`: (default: `"changethis"`) The secret key for the project, used for security, stored in .env, you can generate one with the method above.
-- `first_superuser`: (default: `"[email protected]"`) The email of the first superuser (in .env).
-- `first_superuser_password`: (default: `"changethis"`) The password of the first superuser (in .env).
-- `smtp_host`: (default: "") The SMTP server host to send emails, you can set it later in .env.
-- `smtp_user`: (default: "") The SMTP server user to send emails, you can set it later in .env.
-- `smtp_password`: (default: "") The SMTP server password to send emails, you can set it later in .env.
-- `emails_from_email`: (default: `"[email protected]"`) The email account to send emails from, you can set it later in .env.
-- `postgres_password`: (default: `"changethis"`) The password for the PostgreSQL database, stored in .env, you can generate one with the method above.
-- `sentry_dsn`: (default: "") The DSN for Sentry, if you are using it, you can set it later in .env.
-
-## Backend Development
-
-Backend docs: [backend/README.md](./backend/README.md).
-
-## Frontend Development
-
-Frontend docs: [frontend/README.md](./frontend/README.md).
-
-## Deployment
-
-Deployment docs: [deployment.md](./deployment.md).
-
-## Development
-
-General development docs: [development.md](./development.md).
-
-This includes using Docker Compose, custom local domains, `.env` configurations, etc.
-
-## Release Notes
-
-Check the file [release-notes.md](./release-notes.md).
-
 ## License
 
-The Full Stack FastAPI Template is licensed under the terms of the MIT license.
+The Full Stack FastAPI Template is licensed under the terms of the MIT license.

TASKS.md

@@ -0,0 +1,98 @@
+# Project Tasks
+
+## Project Goals
+
+1. Complete the modular monolith refactoring of the FastAPI backend ✅
+2. Ensure all tests pass and functionality is maintained ✅
+3. Improve code organization and maintainability ✅
+4. Establish clear boundaries between different parts of the application ✅
+
+## Completed Phases
+
+### Phase 1: Complete Event System Implementation ✅
+
+- [x] Create a UserCreatedEvent class in users/domain/events.py
+- [x] Implement user.created event publishing in UserService.create_user method
+- [x] Create an email event handler in email module to send welcome emails
+- [x] Update documentation for event system usage
+- [x] Write tests for the event system implementation
+
+### Phase 2: Finalize Alembic Integration ✅
+
+- [x] Update Alembic environment to import models from all modules
+- [x] Test migration generation with the new modular structure
+- [x] Create migration template for modular table models
+- [x] Document Alembic usage in the modular structure
+
+### Phase 3: Update Remaining Model Imports ✅
+
+- [x] Update remaining import references for non-table models
+- [x] Develop strategy for table models (User, Item) migration
+- [x] Implement the migration strategy for table models
+- [x] Update tests to use the new model imports
+
+### Phase 4: Documentation and Examples ✅
+
+- [x] Update project README with information about the new architecture
+- [x] Add developer guidelines for working with the modular structure
+- [x] Create examples of extending the architecture with new modules
+- [x] Document the event system usage with examples
+
+### Phase 5: Cleanup ✅
+
+- [x] Remove legacy code and unnecessary comments
+- [x] Clean up any temporary workarounds
+- [x] Ensure consistent code style across all modules
+- [x] Final testing to ensure all functionality works correctly
+
+## Completed Phases
+
+### Phase 6: Limpeza Final do Código ✅
+
+- [x] Remover todos os comentários que indicam código temporário ou de transição
+- [x] Remover comentários de código comentado que não será mais utilizado
+- [x] Remover todos os TODOs que já foram implementados
+- [x] Remover arquivos de documentação temporários ou obsoletos
+- [x] Verificar e remover imports não utilizados em todos os arquivos
+
+## Completed Phases
+
+### Phase 7: Limpeza de Documentação ✅
+
+- [x] Atualizar toda a documentação para refletir a arquitetura final
+- [x] Remover referências a arquivos legados na documentação
+- [x] Remover documentação de processos de migração que já foram concluídos
+- [x] Consolidar documentação redundante
+- [x] Garantir que exemplos na documentação usem a estrutura modular atual
+
+## Completed Phases
+
+### Phase 8: Remoção de Arquivos Legados ✅
+
+- [x] Remover arquivo app/crud.py (operações CRUD legadas)
+- [x] Remover arquivos de rotas legadas (app/api/routes/items.py, app/api/routes/login.py, app/api/routes/users.py)
+- [x] Remover testes de rotas legadas (app/tests/api/routes/test_*.py)
+- [x] Verificar que a aplicação continua funcionando após a remoção dos arquivos
+
+### Phase 9: Reorganização da Documentação ✅
+
+- [x] Criar estrutura de pastas docs/ seguindo as práticas recomendadas
+- [x] Criar documentação de introdução (getting-started)
+- [x] Criar documentação de arquitetura detalhada
+- [x] Criar documentação de fluxo de desenvolvimento
+- [x] Criar guias práticos para extensão da API
+- [x] Criar documentação de testes
+- [x] Criar documentação de deployment
+- [x] Remover arquivos de documentação redundantes após migração
+- [x] Garantir consistência de estilo em toda a documentação
+
+## Next Steps
+
+### Phase 10: Melhorias na Experiência do Desenvolvedor
+
+- [ ] Criar ferramentas CLI para gerar novos módulos e componentes
+- [ ] Criar templates para novos módulos e componentes
+- [ ] Adicionar scripts de automação para tarefas comuns de desenvolvimento
+- [ ] Melhorar ferramentas de tratamento de erros e depuração
+- [ ] Aprimorar recursos de logging e monitoramento
+- [ ] Criar guia abrangente de configuração do ambiente de desenvolvimento

TASK_HISTORY/Phase_1_Complete_Event_System_Implementation_20240518.md

@@ -0,0 +1,50 @@
+## Phase 1: Complete Event System Implementation
+
+- [x] Create a UserCreatedEvent class in users/domain/events.py
+- [x] Implement user.created event publishing in UserService.create_user method
+- [x] Create an email event handler in email module to send welcome emails
+- [x] Update documentation for event system usage
+- [x] Write tests for the event system implementation
+
+### Summary of Completed Work
+
+1. **Created UserCreatedEvent class**
+   - Implemented in `app/modules/users/domain/events.py`
+   - Extended the base EventBase class
+   - Added fields for user_id, email, and full_name
+   - Added a convenience publish method
+
+2. **Implemented event publishing in UserService**
+   - Updated `app/modules/users/services/user_service.py`
+   - Added event publishing after successful user creation
+   - Included relevant user data in the event
+
+3. **Created email event handler**
+   - Implemented in `app/modules/email/services/email_event_handlers.py`
+   - Used the @event_handler decorator to subscribe to user.created events
+   - Added handler to send welcome emails to new users
+
+4. **Updated documentation**
+   - Added comprehensive event system documentation to `backend/MODULAR_MONOLITH_IMPLEMENTATION.md`
+   - Included examples, best practices, and architecture details
+   - Documented the event flow between modules
+
+5. **Wrote tests for the event system**
+   - Created core event system tests in `tests/core/test_events.py`
+   - Added user event tests in `tests/modules/users/domain/test_user_events.py`
+   - Implemented email handler tests in `tests/modules/email/services/test_email_event_handlers.py`
+   - Added integration tests in `tests/modules/integration/test_user_email_integration.py`
+
+### Key Achievements
+
+- Successfully implemented a loosely coupled event system
+- Established a pattern for cross-module communication
+- Improved separation of concerns between modules
+- Created comprehensive tests for all components
+- Documented the event system for future developers
+
+### Next Steps
+
+- Proceed to Phase 2: Finalize Alembic Integration
+- Consider adding more domain events for other key operations
+- Expand the event system to cover more use cases

TASK_HISTORY/Phase_2_Finalize_Alembic_Integration_20240518.md

@@ -0,0 +1,44 @@
+## Phase 2: Finalize Alembic Integration
+
+- [x] Update Alembic environment to import models from all modules
+- [x] Test migration generation with the new modular structure
+- [x] Create migration template for modular table models
+- [x] Document Alembic usage in the modular structure
+
+### Summary of Completed Work
+
+1. **Updated Alembic Environment**
+   - Modified `app/alembic/env.py` to import models from all modules
+   - Maintained backward compatibility with legacy models
+   - Added explicit imports for non-table models from each module
+   - Ensured no duplicate table definitions
+
+2. **Tested Migration Generation**
+   - Verified that Alembic can detect models from all modules
+   - Ensured that the migration process works with the modular structure
+   - Identified and addressed import issues
+
+3. **Created Migration Template**
+   - Created `app/alembic/modular_table_migration_example.py` as a reference
+   - Demonstrated how to create migrations for modular table models
+   - Included examples of common migration operations
+
+4. **Documented Alembic Usage**
+   - Created `app/alembic/README_MODULAR.md` with comprehensive documentation
+   - Explained the current hybrid approach during transition
+   - Provided instructions for generating and applying migrations
+   - Included troubleshooting tips and best practices
+
+### Key Achievements
+
+- Successfully integrated Alembic with the modular monolith architecture
+- Maintained backward compatibility during the transition
+- Provided clear documentation for future development
+- Created templates and examples for future migrations
+
+### Next Steps
+
+- Proceed to Phase 3: Update Remaining Model Imports
+- Complete the migration of all models to their respective modules
+- Update all code to use the modular imports
+- Remove legacy models from `app.models` once transition is complete