# 📚 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