add README.md

README.md

@@ -0,0 +1,130 @@
+# C3LF System3
+
+the third try to automate lost&found organization for chaos events. not a complete rewrite, but instead building on top
+of the web frontend of version 2. everything else is new but still API compatible. now with more monorepo.
+
+## Architecture
+
+C3LF System3 integrates a Django-Rest-Framework + WebSocket backend, Vue.js frontend SPA and a minimal LMTP mail server
+integrated with the Django backend. It is additionally deployed with a Postfix mail server as Proxy in front of the
+LMTP socket, a MariaDB database, a Redis cache and an Nginx reverse proxy that serves the static SPA frontend, proxies
+the API requests to the backend and serves the media files in cooperation with the Django backend using the
+`X-Accel-Redirect` header.
+
+The production deployment is automated using Ansible and there are some Docker Compose configurations for development.
+
+## Project Structure
+
+- `core/`  Contains the Django backend with database models, API endpoints, migrations, API tests, and mail server
+  functionalities.
+- `web/` Contains the Vue.js frontend application.
+- `deploy/` Contains deployment configurations and Docker scripts for various development modes.
+
+For more information, see the README.md files in the respective directories.
+
+## Development Modes
+
+There are currently 4 development modes for this Project:
+
+- Frontend-Only
+- Backend-API-Only
+- Full-Stack-Lite 'dev' (docker)
+- **[WIP]** Full-Stack 'testing' (docker)
+
+*Choose the one that is most suited to the feature you want to work on or ist easiest for you to set up ;)*
+
+For all modes it is assumed that you have `git` installed, have cloned the repository and are in the root directory of
+the project. Use `git clone https://git.hannover.ccc.de/c3lf/c3lf-system-3.git` to get the official upstream repository.
+The required packages for each mode are listed separately and also state the specific package name for Debian 12.
+
+### Frontend-Only
+
+This mode is for developing the frontend only. It uses the vue-cli-service (webpack) to serve the frontend and watches
+for changes in the source code to provide hot reloading. The API requests are proxied to the staging backend.
+
+#### Requirements
+
+* Node.js (~20.19.0) (`nodejs`)
+* npm (~9.2.0) (`npm`)
+
+*Note: The versions are not strict, but these are tested. Other versions might work as well.*
+
+#### Steps
+
+```bash
+cd web
+npm intall
+npm run serve
+```
+
+Now you can access the frontend at `localhost:8080` and start editing the code in the `web` directory.
+For more information, see the README.md file in the `web` directory.
+
+### Backend-API-Only
+
+This mode is for developing the backend API only. It also specifically excludes most WebSockets and mail server
+functionalities. Use this mode to focus on the backend API and Database models.
+
+#### Requirements
+
+* Python (~3.11) (`python3`)
+* pip (`python3-pip`)
+* virtualenv (`python3-venv`)
+
+*Note: The versions are not strict, but these are tested. Other versions might work as well.*
+
+#### Steps
+
+```
+python -m venv venv
+source venv/bin/activate
+pip install -r core/requirements.dev.txt
+cd core
+python manage.py test
+```
+
+The tests should run successfully to start and you can now start the TDD workflow by adding new failing tests.
+For more information about the backend and TDD, see the README.md file in the `core` directory.
+
+### Full-Stack-Lite 'dev' (docker)
+
+This mode is for developing the both frontend and backend backend at the same time in a containerized environment. It
+uses the `docker-compose` command to build and run the application in a container. It specifically excludes all mail
+server and most WebSocket functionalities.
+
+#### Requirements
+
+* Docker (`docker.io`)
+* Docker Compose (`docker-compose`)
+
+*Note: Depending on your system, the `docker compose` command might be included in general `docker` or `docker-ce`
+package, or you might want to use podman instead.*
+
+#### Steps
+
+```bash 
+docker-compose -f deploy/dev/docker-compose.yml up --build
+```
+
+The page should be available at [localhost:8080](http://localhost:8080)
+This Mode provides a minimal set of testdata, including a user `testuser` with password `testuser`. The test dataset is
+defined in deploy/testdata.py and can be extended there.
+
+You can now edit code in `/web` and `/core` and changes will be applied to the running page as soon as the file is
+saved.
+
+For details about each part, read `/web/README.md` and `/core/README.md` respectively. To execute commands in the
+container context use 'exec' like
+
+```bash
+docker exec -it c3lf-sys3-dev-core-1 ./manage.py test`
+```
+
+### Full-Stack 'testing' (docker)
+
+**WORK IN PROGRESS**
+
+*will include postfix, mariadb, redis, nginx and the ability to test sending mails, receiving mail and websocket based
+realiteme updates in the frontend. the last step in verification before deploying to the staging system using ansible*
+
+

core/README.md

@@ -0,0 +1,68 @@
+# Core
+
+This directory contains the backend of the C3LF System3 project, which is built using Django and Django Rest Framework.
+
+## Modules
+
+- `authentication`: Handles user authentication and authorization.
+- `files`: Manages file uploads and related operations.
+- `inventory`: Handles inventory management, including events, containers and items.
+- `mail`: Manages email-related functionalities, including sending and receiving emails.
+- `notify_sessions`: Handles real-time notifications and WebSocket sessions.
+- `tickets`: Manages the ticketing system for issue tracking.
+
+## Modules Structure
+
+Most modules follow a similar structure, including the following components:
+
+- `<module>/models.py`: Contains the database models for the module.
+- `<module>/serializers.py`: Contains the serializers for the module models.
+- `<module>/api_<api_version>.py`: Contains the API views and endpoints for the module.
+- `<module>/migrations/`: Contains database migration files. Needs to contain an `__init__.py` file to be recognized as
+  a Python package and automatically migration creation to work.
+- `<module>/tests/<api_version>/test_<feature_model_or_testcase>.py`: Contains the test cases for the module.
+
+## Development Setup
+
+follow the instructions under 'Backend-API-Only' or 'Fullstack-Lite' in the root level `README.md` to set up a
+development environment.
+
+## Test-Driven Development (TDD) Workflow
+
+The project follows a TDD workflow to ensure code quality and reliability. Here is a step-by-step guide to the TDD
+process:
+
+1. **Write a Test**: Start by writing a test case for the new feature or bug fix. Place the test case in the appropriate
+   module within the `<module>/tests/<api_version>/test_<feature_model_or_testcase>.py` file.
+
+2. **Run the Test**: Execute the test to ensure it fails, confirming that the feature is not yet implemented or the bug
+   exists.
+    ```bash
+    python manage.py test
+    ```
+
+3. **Write the Code**: Implement the code required to pass the test. Write the code in the appropriate module within the
+   project.
+
+4. **Run the Test Again**: Execute the test again to ensure it passes.
+    ```bash
+    python manage.py test
+    ```
+
+5. **Refactor**: Refactor the code to improve its structure and readability while ensuring that all tests still pass.
+
+6. **Repeat**: Repeat the process for each new feature or bug fix.
+
+## Measuring Test Coverage
+
+The project uses the `coverage` package to measure test coverage. To generate a coverage report, run the following
+command:
+
+```bash
+coverage run --source='.' manage.py test
+coverage report
+```
+
+## Additional Information
+
+For more detailed information on the project structure and development modes, refer to the root level `README.md`.