Archive Manager is a Python CLI for managing archives through independent, extensible modules. The first implemented module focuses on contact management, with a structure designed to grow into additional domains over time.
| Area | Highlights |
|---|---|
| Contact workflows | Create, read, update, soft-delete, and search by name, email, or phone |
| Listing and pagination | Contact list uses a bounded limit (default and max: 20), footer metadata (page/pages and from-to/total), and next/previous navigation when total results are greater than 10 |
| Duplicate prevention | Phone canonicalization detects equivalent formats (for example, +34 600 000 000 and +34600000000) |
| Internationalization | English and Spanish resources for prompts, menus, and outputs |
| Architecture | Clean Architecture, protocol-based interfaces, and dependency injection |
| Persistence | SQLAlchemy repositories over SQLite with automatic bootstrap |
| CLI experience | Rich terminal UI with InquirerPy interactive prompts |
| Observability | Rotating logs by severity (10 MB, 5 backups) |
- Python 3.11 or newer
git clone https://github.com/Paul-Barzallo/archive-manager-python.git
cd archive-manager-python
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate
pip install -e .
archive-manager cliRun API server:
archive-manager apiShow available commands:
archive-managerAPI options:
archive-manager api --host 0.0.0.0 --port 3000 --reloadOpen interactive API docs at http://127.0.0.1:8000/docs.
Configuration precedence (highest to lowest):
--debugCLI flag- Constructor keyword arguments (tests/programmatic use)
- Environment variables (
APP_prefix,__nested delimiter) .envfileconfig.{environment}.yamlconfig.yaml- Pydantic defaults
Static resources (i18n JSON files, SQL bootstrap scripts) are bundled in the
package. Runtime artifacts (database and logs) are written under data/.
Use .env for sensitive values (API keys, tokens, credentials). The file is
excluded from version control; use .env.example as a template.
APP_DATABASE__URL=sqlite:///data/db/archive-manager.sqlite
APP_DEBUG=trueSQLite database:
- Created automatically on first run
- Stored in
data/db/
Rotating logs (RotatingFileHandler) in data/logs/:
| File | Level |
|---|---|
debug.log |
DEBUG (only with --debug) |
info.log |
INFO and above |
error.log |
ERROR and above |
All log messages are emitted in English, regardless of UI language.
Language resources live under resources/i18n/{lang}/:
| Directory | Purpose |
|---|---|
visual/ |
Prompts, labels, confirmations, field names |
output/ |
Error, warning, and success messages |
contact/ |
Contact-module menus and table layouts |
Language defaults to the system locale and can be overridden in config.yaml.
Run tests:
python -m pytestLint and format:
ruff check src/ tests/
ruff format src/ tests/Windows task runner:
.\tasks.ps1 test
.\tasks.ps1 lint
.\tasks.ps1 format
.\tasks.ps1 check
.\tasks.ps1 clean
.\tasks.ps1 installPushes and pull requests to main or develop run
.github/workflows/ci.yaml with:
- Lint (Ruff format + lint checks)
- Type check (mypy)
- Tests (Ubuntu and Windows, Python 3.11 and 3.12)
- Coverage artifact upload
The test stage depends on lint and type-checking. All checks must pass before merge.
src/archive_manager/
├── __init__.py # Entry point dispatcher (cli/api)
├── core/ # Domain layer (no external dependencies)
│ ├── errors.py # Exception hierarchy
│ ├── entities/ # Domain models and validators
│ └── interfaces/ # Protocol contracts
├── application/ # Use-case layer (depends on core)
│ ├── dto/ # Data transfer objects
│ └── services/ # Business logic and policies
├── infrastructure/ # External integrations (depends on core)
│ ├── config/ # Settings, logging, session
│ ├── i18n/ # Message, menu, and table loaders
│ └── persistence/ # Repository, ORM, mappers, bootstrap
├── adapters/ # Delivery mechanisms (depends on all layers)
│ ├── cli/ # Service-driven state machine and Rich UI
│ │ └── main.py # CLI composition root
│ └── api/ # FastAPI app, dependencies, routers, schemas
└── resources/
└── i18n/ # JSON resource files (en/, es/)
- ARCHITECTURE.md: layer design, DI strategy, errors, persistence decisions
- DEVELOPMENT.md: setup, conventions, i18n workflow, patterns
- CHANGELOG.md: release history
MIT License. See LICENSE.