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

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:

cd backend/app
python main.py

Frontend:

cd frontend
npm install
npm start

📡 API Endpoints

1. Inicjalizacja systemu

POST /api/init
Content-Type: application/json

{
  "password": "twoje_bezpieczne_haslo_8znaków_min"
}

Response:

{
  "status": "success",
  "recovery_key": "a1b2c3d4e5f6...",
  "message": "System initialized. Save recovery key in safe place."
}

2. Logowanie - hasłem głównym

POST /api/login
Content-Type: application/json

{
  "password": "twoje_haslo",
  "is_recovery": false
}

Response:

{
  "status": "success",
  "message": "Successfully authenticated"
}

3. Logowanie - kluczem awaryjnym

POST /api/login
Content-Type: application/json

{
  "password": "a1b2c3d4e5f6...",
  "is_recovery": true
}

Response:

{
  "status": "success",
  "message": "Authenticated with recovery key. Please change password."
}

4. Sprawdzenie statusu

GET /api/status

Response:

{
  "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)

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

# Backend
pip install -r requirements.txt

# Lub z uv:
cd backend/app && uv sync

# Frontend
cd frontend && npm install

Testowanie API

# 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

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

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

ALLOWED_ORIGINS = ["http://localhost:3000"]

Problem: Baza danych uszkodzona

rm archivium.db        # Usuń stary plik
python launcher.py     # Przeinicjalizuj

Problem: npm start nie działa

cd frontend
rm -rf node_modules package-lock.json
npm install
npm start

👥 Współpraca (Git)

# 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

📞 Support

Kontakt: SzymonS @ gitea.archvium.eu

---

Ostatnia aktualizacja: April 9, 2026