Monorepo Integration: Unified Backend, Frontend & Documentation
- Reorganize project into monorepo structure - backend/app/ - New FastAPI backend (modular with src/) - backend/legacy/ - Legacy database modules (relational & vector) - frontend/ - React text editor application - Add launcher.py for easy full-stack startup - Complete documentation in README.md - Quick start guide - API endpoints reference - Development setup - Troubleshooting - Refactor main.py to 35 lines (app configuration only) - Update .gitignore for full-stack project - Add CHANGELOG.md with version history (v0.1.0-v0.1.1) Structure is now clean and ready for team collaboration.
This commit is contained in:
Krzysztof Cieślik
334
README.md
Normal file
334
README.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# 📚 Archivium - System Zarządzania Archiwum
|
||||
|
||||
**Archivium** to integrowany system do szyfrowania, przechowywania i wyszukiwania archiwów z bezpiecznym uwierzytelnianiem i interfejsem edytora tekstu.
|
||||
|
||||
## 🏗️ Architektura projektu
|
||||
|
||||
```
|
||||
archivium/
|
||||
├── backend/
|
||||
│ ├── app/ # Nowoczesny backend FastAPI
|
||||
│ │ ├── src/
|
||||
│ │ │ ├── config.py # Konfiguracja
|
||||
│ │ │ ├── models.py # Modele bazy
|
||||
│ │ │ ├── schemas.py # Walidacja
|
||||
│ │ │ ├── database.py # Zarządzanie BD
|
||||
│ │ │ ├── security.py # Hashing hasła
|
||||
│ │ │ └── routers/ # Endpointy API
|
||||
│ │ │ ├── init.py
|
||||
│ │ │ ├── login.py
|
||||
│ │ │ └── status.py
|
||||
│ │ ├── main.py # Punkt wejścia (35 linii)
|
||||
│ │ └── pyproject.toml
|
||||
│ │
|
||||
│ └── legacy/ # Stare moduły bazy danych
|
||||
│ ├── relational_database.py
|
||||
│ └── vector_database.py
|
||||
│
|
||||
├── frontend/ # React aplikacja (edytor tekstu)
|
||||
│ ├── public/
|
||||
│ ├── src/
|
||||
│ └── package.json
|
||||
│
|
||||
├── launcher.py # Uruchamiacz całej aplikacji
|
||||
├── requirements.txt # Zależności Python
|
||||
├── README.md # Ta dokumentacja
|
||||
├── CHANGELOG.md # Historia zmian
|
||||
└── .git/ # Repozytorium Git
|
||||
```
|
||||
|
||||
## 🚀 Szybki start
|
||||
|
||||
### Uruchomienie całej aplikacji (jedno polecenie)
|
||||
|
||||
```bash
|
||||
python launcher.py
|
||||
```
|
||||
|
||||
To uruchomi:
|
||||
- ✅ Backend FastAPI (port 8000)
|
||||
- ✅ Frontend React (port 3000)
|
||||
- ✅ Otworzy przeglądarkę na http://localhost:3000
|
||||
|
||||
### Ręczne uruchomienie poszczególnych części
|
||||
|
||||
**Backend:**
|
||||
```bash
|
||||
cd backend/app
|
||||
python main.py
|
||||
```
|
||||
|
||||
**Frontend:**
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
|
||||
## 📡 API Endpoints
|
||||
|
||||
### 1. Inicjalizacja systemu
|
||||
```http
|
||||
POST /api/init
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"password": "twoje_bezpieczne_haslo_8znaków_min"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"recovery_key": "a1b2c3d4e5f6...",
|
||||
"message": "System initialized. Save recovery key in safe place."
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Logowanie - hasłem głównym
|
||||
```http
|
||||
POST /api/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"password": "twoje_haslo",
|
||||
"is_recovery": false
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"message": "Successfully authenticated"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Logowanie - kluczem awaryjnym
|
||||
```http
|
||||
POST /api/login
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"password": "a1b2c3d4e5f6...",
|
||||
"is_recovery": true
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"message": "Authenticated with recovery key. Please change password."
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Sprawdzenie statusu
|
||||
```http
|
||||
GET /api/status
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"is_initialized": true
|
||||
}
|
||||
```
|
||||
|
||||
## 🔐 Bezpieczeństwo
|
||||
|
||||
### Zaimplementowane zabezpieczenia:
|
||||
- ✅ **Hashing haseł** - Argon2 (type="ID")
|
||||
- ✅ **Losowe klucze awaryjne** - 32 znaki hex
|
||||
- ✅ **CORS** - ograniczony do zaufanych domen
|
||||
- ✅ **Walidacja danych** - Pydantic
|
||||
- ✅ **Dwie ścieżki dostępu** - hasło główne + klucz awaryjny
|
||||
|
||||
### Zmienne środowiskowe (.env)
|
||||
```bash
|
||||
ENVIRONMENT=development # development | production
|
||||
DATABASE_PATH=archivium.db # lokalizacja bazy
|
||||
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
|
||||
```
|
||||
|
||||
### Rekomendacje produkcyjne:
|
||||
1. Użyj **PostgreSQL** zamiast SQLite
|
||||
2. Włącz **HTTPS/SSL**
|
||||
3. Dodaj **rate limiting**
|
||||
4. Włącz **logging i monitoring**
|
||||
5. Regularne **backupy** bazy danych
|
||||
6. Przechowuj sekrety w zmiennych środowiskowych
|
||||
|
||||
## 📚 Szczegółowa dokumentacja struktury
|
||||
|
||||
### Backend - Endpointy (src/routers/)
|
||||
|
||||
**init.py** - `POST /api/init`
|
||||
- Inicjalizuje system
|
||||
- Generuje recovery key (32 znaki)
|
||||
- Hashuje hasło główne z Argon2
|
||||
|
||||
**login.py** - `POST /api/login`
|
||||
- Logowanie hasłem głównym lub kluczem awaryjnym
|
||||
- Weryfikuje hash haseł
|
||||
- Zwraca status autoryzacji
|
||||
|
||||
**status.py** - `GET /api/status`
|
||||
- Sprawdza czy system zainicjalizowany
|
||||
- Zwraca boolean `is_initialized`
|
||||
|
||||
### Backend - Core modules (src/)
|
||||
|
||||
**config.py** - Konfiguracja
|
||||
- CORS configuration
|
||||
- DATABASE_PATH z zmiennych środowiskowych
|
||||
- ALLOWED_ORIGINS
|
||||
|
||||
**models.py** - SQLAlchemy ORM
|
||||
- SecurityConfig model
|
||||
- Tabela `security_config`
|
||||
- Przechowuje hashe haseł i kluczy
|
||||
|
||||
**schemas.py** - Pydantic validation
|
||||
- InitRequest - walidacja do /api/init
|
||||
- LoginRequest - walidacja do /api/login
|
||||
|
||||
**database.py** - Zarządzanie bazą
|
||||
- SQLite setup
|
||||
- Session management
|
||||
- `init_db()` - inicjalizuje schemat
|
||||
- `get_db()` - dependency injection dla sessionów
|
||||
|
||||
**security.py** - Funkcje bezpieczeństwa
|
||||
- `hash_password(password: str) -> str`
|
||||
- `verify_password(password: str, hash_value: str) -> bool`
|
||||
- `generate_recovery_key() -> str`
|
||||
|
||||
**main.py** - FastAPI aplikacja (35 linii!)
|
||||
- Konfiguracja CORS middleware
|
||||
- Include routery
|
||||
- Startup event dla init_db()
|
||||
|
||||
## 🛠️ Development
|
||||
|
||||
### Instalacja dependencies
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
pip install -r requirements.txt
|
||||
|
||||
# Lub z uv:
|
||||
cd backend/app && uv sync
|
||||
|
||||
# Frontend
|
||||
cd frontend && npm install
|
||||
```
|
||||
|
||||
### Testowanie API
|
||||
|
||||
```bash
|
||||
# Curl - Inicjalizacja
|
||||
curl -X POST http://localhost:8000/api/init \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"password": "TestPassword123"}'
|
||||
|
||||
# Curl - Logowanie
|
||||
curl -X POST http://localhost:8000/api/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"password": "TestPassword123", "is_recovery": false}'
|
||||
|
||||
# Status
|
||||
curl http://localhost:8000/api/status
|
||||
```
|
||||
|
||||
### Dokumentacja interaktywna
|
||||
|
||||
Gdy serwer działa, otwórz: **http://localhost:8000/docs**
|
||||
- Swagger UI do testowania API
|
||||
- Automatyczna dokumentacja OpenAPI
|
||||
- Try it out - testuj bezpośrednio z przeglądarki
|
||||
|
||||
## 📝 Historia zmian
|
||||
|
||||
Pełna historia zmian w [CHANGELOG.md](CHANGELOG.md)
|
||||
|
||||
### v0.1.1 - Monorepo Integration
|
||||
- Reorganizacja całego projektu do struktury monorepo
|
||||
- Backend w `backend/app/` (35 linii main.py!)
|
||||
- Launcher do uruchamiania całej aplikacji
|
||||
- Integracja z starym kodem z `Database/` i `TextEditor/`
|
||||
- Kompletna dokumentacja
|
||||
|
||||
### v0.1.0 - Refactorization
|
||||
- Refaktoryzacja kodu, usunięcie komentarzy
|
||||
- Modularyzacja na src/
|
||||
- Bezpieczeństwo (CORS, Argon2, walidacja)
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Problem: Port 8000 już w użyciu
|
||||
```bash
|
||||
# Zmień w backend/app/main.py lub użyj:
|
||||
cd backend/app && uv run uvicorn main:app --port 8001
|
||||
```
|
||||
|
||||
### Problem: Frontend nie łączy się z backendem
|
||||
Sprawdź w `backend/app/src/config.py`:
|
||||
```python
|
||||
ALLOWED_ORIGINS = ["http://localhost:3000"]
|
||||
```
|
||||
|
||||
### Problem: Baza danych uszkodzona
|
||||
```bash
|
||||
rm archivium.db # Usuń stary plik
|
||||
python launcher.py # Przeinicjalizuj
|
||||
```
|
||||
|
||||
### Problem: npm start nie działa
|
||||
```bash
|
||||
cd frontend
|
||||
rm -rf node_modules package-lock.json
|
||||
npm install
|
||||
npm start
|
||||
```
|
||||
|
||||
## 👥 Współpraca (Git)
|
||||
|
||||
```bash
|
||||
# Clone repozytorium
|
||||
git clone http://gitea.archvium.eu:30230/SzymonS/Kod.git
|
||||
|
||||
# Stwórz feature branch
|
||||
git checkout -b feature/my-feature
|
||||
|
||||
# Commit
|
||||
git add .
|
||||
git commit -am "Add new feature"
|
||||
|
||||
# Push
|
||||
git push origin feature/my-feature
|
||||
```
|
||||
|
||||
## 📦 Zależności
|
||||
|
||||
### Backend (Python)
|
||||
- **FastAPI** (0.104.0+) - Framework
|
||||
- **SQLAlchemy** (2.0.0+) - ORM
|
||||
- **Pydantic** (2.5.0+) - Walidacja
|
||||
- **Passlib[argon2]** (1.7.4+) - Hashing
|
||||
- **Uvicorn** (0.24.0+) - ASGI server
|
||||
|
||||
### Frontend (Node.js)
|
||||
- **React** - UI framework
|
||||
- Inne (patrz: `frontend/package.json`)
|
||||
|
||||
Pełna lista: [requirements.txt](requirements.txt)
|
||||
|
||||
## 📞 Support
|
||||
|
||||
Kontakt: SzymonS @ gitea.archvium.eu
|
||||
|
||||
---
|
||||
|
||||
**Ostatnia aktualizacja:** April 9, 2026
|
||||
Reference in New Issue
Block a user