How pzio-2026/pzio works
1. Overall shape
- PZIO is a full-stack Jira-like task management system with a clear split between a Python backend and a React/TypeScript frontend.
- The backend exposes a JSON API; the frontend is a single-page app that consumes that API.
2. Backend runtime and core framework
- The backend lives under backend/pzio and is built with FastAPI and SQLAlchemy.
- Startup appears centered around pzio/main.py, with shared app configuration in config.py, database setup in db.py, and a CLI/module entrypoint in __main__.py.
3. Backend module boundaries
- The backend is organized into feature modules: auth, admin, projects, tasks, and communication.
- Each module typically has its own router.py, service.py, models.py, and schemas.py, which suggests a clean layering of:
- HTTP routing
- business logic
- persistence models
- request/response DTOs
4. Authentication and authorization flow
- The auth module handles registration, login, OAuth, password reset, profile management, roles, and security concerns.
- Authorization is role-based, with roles such as TeamMember, Manager, and Administrator.
- The README notes a bootstrap rule: the first registered user becomes the administrator, and later users default to team member.
5. Admin subsystem
- The admin module provides operational endpoints for system management, including users, activity logs, backups, and task types.
- This module is distinct from normal project/task workflows and likely exposes privileged functionality for administrators only.
6. Project and task domain
- projects models the project-level domain: projects, members, sprints, backlog, and project-specific permissions.
- tasks holds task-level behavior and detail views, likely including task state, assignment, and worklog-related persistence.
- The frontend structure mirrors this split, which indicates these are the main business entities in the app.
7. Communication subsystem
- communication handles task-related collaboration features such as comments, attachments, and notifications.
- It has a dedicated service layer plus support for message delivery abstractions, including smtp.py and mock.py, implying pluggable notification transport for real email vs test/mock execution.
8. Data and persistence
- Persistence is database-backed through SQLAlchemy, with SQLite for development and PostgreSQL for production.
- The app auto-creates its database schema on first run, so there is no manual migration/bootstrap script in the normal startup path.
- backend/pzio/modules/projects/seed.py suggests some domain seed data is loaded for projects or task types.
9. Frontend runtime and structure
- The frontend is a React + TypeScript app in frontend/src, built with Vite and styled with Tailwind CSS.
- It is organized by the same business modules as the backend: auth, projects, tasks, communication, and admin.
- Shared app composition lives in components such as App.tsx, AppLayout.tsx, and ConfirmProvider.tsx.
10. Frontend-to-backend data flow
- The frontend uses module-specific API clients under src/api and src/modules/*/api.ts to call backend endpoints.
- Pages and components render domain data from those clients, and authenticated state is managed through AuthProvider, context/hooks, and local storage helpers.
- Protected routes enforce login-gated navigation in the client, while backend permissions remain the source of truth.
11. UI domains and user journeys
- Authentication screens cover login, registration, password reset, OAuth callback, and profile editing.
- Project screens cover list/overview/board/backlog/members/sprints, while task screens focus on task lists and task detail.
- Admin screens expose operational control panels such as users, backups, task history, and task types.
12. API documentation and contract
- The repository includes generated API documentation in docs/api/openapi.yaml.
- backend/scripts/dump_openapi.py indicates the backend OpenAPI spec is exported from the FastAPI app and checked into docs, so the API contract is a first-class artifact.
13. Development, testing, and deployment
- The repo is set up for CI with GitHub Actions for backend pytest and frontend npm builds.
- Docker Compose runs the full stack with PostgreSQL, backend, and frontend; each service has its own Dockerfile.
- backend/README.md and frontend/README.md likely contain component-specific startup details, but the top-level repo is designed for local dev and containerized deployment.
14. Architecture diagram takeaway
- The main diagram should show: browser SPA → frontend API client → FastAPI backend routers → service layer → SQLAlchemy models → database, with a side path for communication/notifications and admin-only operations.
- The most important boundaries are frontend vs backend, public auth vs privileged admin, and domain modules vs shared infrastructure.
Main entry points: main.py App entry · App.tsx App shell · client.ts API client · services.py Services
Components 20
Frontend
React/TypeScript SPA and UI modules
- Browser SPA · User-facing single-page app
frontend/src/main.tsx - App shell · Top-level layout, providers, and protected routing
frontend/src/components/App.tsx - Auth UI · Login, register, profile, and auth state
frontend/src/modules/auth/pages/LoginPage.tsx - Projects UI · Project overview, backlog, board, members, and sprints
frontend/src/modules/projects/pages/ProjectsOverviewPage.tsx - Tasks UI · Task list, task detail, and worklog views
frontend/src/modules/tasks/pages/TaskDetailPage.tsx - Comms UI · Comments, attachments, and collaboration panel
frontend/src/modules/communication/components/TaskCommunicationPanel.tsx - Admin UI · Operational panels for users, backups, task types, and history
frontend/src/modules/admin/pages/AdminPanelPage.tsx - API client · Shared client and per-module API adapters
frontend/src/api/client.ts
Backend
FastAPI application, domain modules, and persistence
- App entry · Backend application startup and router composition
backend/pzio/main.py - Config & DB · Settings, database setup, and schema initialization
backend/pzio/config.py - Auth API · Registration, login, OAuth, password reset, roles, and profile
backend/pzio/modules/auth/router.py - Projects API · Projects, members, sprints, backlog, and permissions
backend/pzio/modules/projects/router.py - Tasks API · Task routing, task details, and task state handling
backend/pzio/modules/tasks/router.py - Comm API · Comments, attachments, notifications, and delivery abstractions
backend/pzio/modules/communication/router.py - Admin API · User administration, activity logs, backups, and task types
backend/pzio/modules/admin/router.py - Services · Business logic across feature modules
backend/pzio/modules/projects/services.py - Models · Domain persistence models shared by feature modules
backend/pzio/modules/projects/models.py - Notifications · SMTP and mock notification transport
backend/pzio/modules/communication/smtp.py
Shared
API contract, docs, and deployment assets
- OpenAPI spec · Generated API documentation exported from FastAPI
docs/api/openapi.yaml - Compose stack · Containerized backend, frontend, and PostgreSQL runtime
docker-compose.yml
Connections 28
- Browser SPA → App shell: renders · The SPA is composed by the top-level shell
- App shell → Auth UI: routes to · Authentication flows live in the auth module
- App shell → Projects UI: routes to · Project views are mounted through the shell
- App shell → Tasks UI: routes to · Task pages are mounted through the shell
- App shell → Comms UI: routes to · Communication views are embedded in task/project pages
- App shell → Admin UI: routes to · Admin pages are protected by the client router
- Auth UI → API client: calls · Auth forms submit through the API layer
- Projects UI → API client: calls · Project screens load and mutate via API adapters
- Tasks UI → API client: calls · Task screens fetch and update task data via API adapters
- Comms UI → API client: calls · Comment and attachment actions go through the API layer
- Admin UI → API client: calls · Admin panels use backend administration endpoints
- API client → App entry: HTTP JSON · Frontend clients talk to the FastAPI backend
- App entry → Config & DB: bootstraps · Startup loads configuration and database state
- App entry → Auth API: mounts · Auth routes are registered in the app
- App entry → Projects API: mounts · Project routes are registered in the app
- App entry → Tasks API: mounts · Task routes are registered in the app
- App entry → Comm API: mounts · Communication routes are registered in the app
- App entry → Admin API: mounts · Admin routes are registered in the app
- Auth API → Services: delegates · Auth routing delegates to business logic
- Projects API → Services: delegates · Project routing delegates to business logic
- Tasks API → Services: delegates · Task routing delegates to business logic
- Comm API → Notifications: uses · Communication service sends via SMTP or mock transports
- Admin API → Services: delegates · Admin operations reuse service-layer logic
- Services → Models: persists · Business logic reads and writes SQLAlchemy models
- Models → Config & DB: stored in · Domain state is backed by the configured database
- App entry → OpenAPI spec: exports · The FastAPI app is the source of the published contract
- Compose stack → App entry: runs · Compose starts the backend service
- Compose stack → Browser SPA: serves · Compose includes the frontend runtime