System Requirements Document (SRD)

Project: stone-tax Prepared for: Micro Mind Country/Locale: Pakistan (PK) Date: 2026-02-28 Version: 1.0.0

1. Introduction

This document defines the System Requirements for stone-tax — an IRIS-inspired Income Tax Return (ITR) Filing System designed for local deployment in Pakistan. Built for tax professionals and individual filers, stone-tax replicates and extends the core functionality of the FBR IRIS portal with multi-role access, custom dashboards, and a modern responsive interface.

This SRD serves as the single source of truth for all stakeholders involved in the design, development, and deployment of the stone-tax platform. The system is intended to run on a local WampServer/localhost environment, targeting Pakistani tax consultants, accountants, and individual taxpayers.

2. System Overview

stone-tax is a full-stack web application modeled after Pakistan's IRIS Income Tax Return Filing System. It enables users to file income tax returns, manage withholding statements, track payments, communicate via an inbox/outbox system, and manage their tax profiles — all within a secure, locally hosted environment.

The system supports three primary user roles: Admin, Tax Consultant/Accountant, and Individual Taxpayer (User). Each role has a tailored dashboard and permission set. The application is built for local business use, making it ideal for tax consultancy firms, accounting offices, and individual professionals managing client filings in Pakistan.

Key highlights:

• IRIS-style multi-level dashboard with action cards
• Multi-role access: Admin, Tax Consultant, Accountant, Individual User
• Tax return filing, tracking, and viewing
• Messaging system (Inbox / Outbox / Drafts)
• Payment tracking and audit logging
• Document and withholding statement management
• Local deployment via Docker / docker-compose on WampServer or equivalent

3. Functional Requirements

3.1 Authentication & Access

• As a User, I should be able to register a new account with my NTN/CNIC and personal details
• As a User, I should be able to log in securely using my username and password
• As a User, I should be able to log out of the system
• As a Admin, I should be able to create a default admin account with credentials during initial setup
• As a Admin, I should be able to manage user accounts and assign roles

3.2 Dashboard

• As a User, I should be able to see a multi-level dashboard with 7 action cards upon login
• As a Tax Consultant, I should be able to see a custom dashboard showing an overview of all my clients' tax returns, pending tasks, and payment statuses
• As an Accountant, I should be able to see a custom dashboard with client filing analytics and trends
• As an Admin, I should be able to see a system-wide dashboard with user statistics, filing summaries, and audit logs

3.3 Tax Return Filing

• As a User, I should be able to file a new income tax return
• As a User, I should be able to edit a draft tax return before submission
• As a User, I should be able to view the details of any previously filed tax return
• As a User, I should be able to track the status of my submitted tax returns
• As a Tax Consultant, I should be able to file and manage tax returns on behalf of my clients
• As a Admin, I should be able to view and manage all tax returns in the system

3.4 Messaging System

• As a User, I should be able to receive messages in my Inbox
• As a User, I should be able to send messages via the Outbox
• As a User, I should be able to save messages as Drafts before sending
• As a Tax Consultant, I should be able to communicate with clients through the messaging system
• As an Admin, I should be able to broadcast system-wide announcements via the messaging system

3.5 Profile Management

• As a User, I should be able to view and update my profile information
• As a User, I should be able to change my account password securely
• As a Tax Consultant, I should be able to manage my client list within my profile
• As an Admin, I should be able to manage and edit any user's profile

3.6 Payment Tracking

• As a User, I should be able to view my payment history and pending dues
• As a Tax Consultant, I should be able to track payment statuses for all assigned clients
• As an Admin, I should be able to view and manage all payments in the system

3.7 Documents & Withholding Statements

• As a User, I should be able to upload and manage tax-related documents
• As a User, I should be able to view and manage withholding statements
• As a User, I should be able to manage sales invoices within the system
• As a Tax Consultant, I should be able to access documents submitted by their assigned clients

3.8 Audit & Security

• As an Admin, I should be able to view a complete audit log of all user actions in the system
• As an Admin, I should be able to enforce role-based access controls across all modules
• As a User, I should be assured that all my data is validated and protected against unauthorized access

4. User Personas

4.1 Admin

The system administrator responsible for managing users, roles, system settings, and audit logs. Has full access to all modules. Typically an IT manager or senior staff member at a tax consultancy firm.

4.2 Tax Consultant

A licensed tax professional who manages the filings of multiple clients. Has access to a dedicated client management dashboard, can file returns on behalf of clients, and communicates with clients through the messaging system.

4.3 Accountant

A financial professional who assists clients with bookkeeping, withholding statements, and payment tracking. Similar permissions to a Tax Consultant but focused on financial records rather than filing.

4.4 Individual User (Taxpayer)

A Pakistani taxpayer filing their own income tax return. Can manage their own profile, file returns, track payments, upload documents, and communicate with their assigned consultant.

5. Visuals, Colors, and Theme

5.1 Design Inspiration

The stone-tax interface is inspired by the FBR IRIS portal — clean, professional, and government-grade — while being elevated with a modern, responsive design suitable for local Pakistani business users.

5.2 Color Palette

5.3 Typography

• Headings: Inter / Poppins (Bold)
• Body: Inter / Roboto (Regular)
• Data/Tables: Roboto Mono (for tax figures and amounts)

5.4 UI Components

• Card-based dashboard layout (IRIS-style 7-action card grid)
• Sidebar navigation with collapsible menu
• Status badges (Pending, Filed, Approved, Rejected)
• Data tables with sorting, filtering, and pagination
• Toast notifications for real-time feedback
• Modal dialogs for confirmations and quick views

6. Signature Design Concept

"The Government Vault" — A Living Paper-File Portal

Imagine landing on stone-tax and being greeted by what feels like the inside of a pristine, modernized government tax office — but made entirely of light and motion.

The Landing / Login Page: The background is a subtle animated blueprint grid — light blue graph paper lines that gently pulse and breathe, evoking the precision of official government documents. Over this grid, a large Pakistan Green (#00A651) crescent and star watermark slowly rotates at 1% opacity, always present, deeply patriotic.

The login card floats at center screen like an official document lifted off a desk — it casts a soft, real-time shadow that shifts as you hover your cursor, as if you're physically picking it up. The card has a faint embossed texture, mimicking official government stationery.

Dashboard Entry Animation: Upon successful login, the screen doesn't fade or slide — instead, it performs a "stamp and file" transition: a green rubber stamp graphic slams down with a satisfying sound cue ("VERIFIED"), then the entire screen peels back like a folder being opened, revealing the dashboard beneath. Different stamps for different roles — red for Admin, amber for Consultant, green for User.

The 7 Action Cards: Each of the 7 dashboard action cards is designed to look like a physical government file folder — thick card stock edges, a colored tab label at the top, and a small paper clip icon. On hover, the card lifts and tilts (3D CSS transform), the folder tab flips up, and the card face reveals an animated micro-statistic (e.g., "3 Returns Pending" counts up in real time). The folders are arranged on a virtual desk surface with a realistic wood-grain gradient.

Tax Return Filing Flow: The filing wizard feels like filling out a physical form under glass — each field illuminates with a soft yellow highlight (like a highlighter pen) as you focus on it. Completed sections get a small green checkmark stamp. When the return is submitted, a dramatic "FILED" stamp animation in Pakistan Green splashes across the form, followed by a satisfying paper-shuffle sound.

Consultant Client Overview: The consultant dashboard presents clients as individual manila file folders in a horizontal scrolling carousel. Each folder shows the client's initials on the tab, their filing status as a colored tag, and a quick-peek animation when hovered — the top of the folder opens slightly to reveal the first data point (last filing date, outstanding amount).

Color-Shifting Navbar: The top navigation bar subtly shifts its accent stripe color based on the active module — blue for Dashboard, green for Returns, amber for Payments, red for Alerts — giving users instant spatial awareness within the app.

Micro-interactions:

• Saving a draft causes a small paper airplane to fly across the screen
• Receiving a new message triggers a letter-envelope icon to "open" in the notification bell
• Audit log entries appear with a typewriter effect, as if being typed in real time
• Payment confirmed — coins briefly cascade from the top of the card

This concept transforms a typically dry government tax portal into an experience that feels alive, tactile, and uniquely Pakistani — blending the gravity of official documentation with the delight of thoughtful, modern UI design.

7. Non-Functional Requirements

7.1 Performance

• Dashboard and primary pages must load within 2 seconds on localhost
• The system must support at least 50 concurrent local users without degradation
• Database queries on tax return listings must complete within 500ms

7.2 Security

• All passwords must be hashed (bcrypt or Argon2) before storage
• Role-based access control (RBAC) must be enforced on every route/endpoint
• All user inputs must be validated and sanitized to prevent SQL injection and XSS
• Session tokens must expire after 30 minutes of inactivity
• Audit logging must capture all Create, Update, Delete actions with user ID and timestamp

7.3 Usability

• The UI must be fully responsive across desktop, tablet, and mobile viewports
• The system must follow WCAG 2.1 AA accessibility standards
• All forms must provide inline validation feedback in real time
• The interface language is English, with support for Urdu labels as a future enhancement

7.4 Reliability

• The system must achieve 99% uptime during local business hours (9 AM – 6 PM PKT)
• All critical operations (filing, payments) must be transactional to prevent partial data corruption
• Daily automated database backups must be supported via Docker volume mounts

7.5 Maintainability

• Codebase must follow modular architecture with clear separation of concerns
• Database schema changes must be managed via Alembic migrations
• All environment-specific settings must be stored in .env files, never hardcoded
• Code must be documented with inline comments and a developer README

7.6 Localization

• Default currency: PKR (Pakistani Rupee — ₨)
• Default timezone: Asia/Karachi (PKT, UTC+5)
• Tax year: July 1 – June 30 (Pakistan fiscal year)
• Date format: DD/MM/YYYY

8. Tech Stack

8.1 Frontend

8.2 Backend

8.3 Database

8.4 Local Orchestration

8.5 Server-Side Orchestration (Future/Scale)

8.6 Notable Exclusions

The following were considered but not selected for this project phase:

• NoSQL (MongoDB) — not required; all data is relational
• VectorDB (WeaviateDB) — no AI/semantic search features in scope
• AI Models (GPT, Claude, Gemini) — not required for core tax filing functionality
• React Native — local web deployment only; no mobile app in this phase

9. Assumptions and Constraints

Assumptions

• The system will be deployed on a local LAN or localhost environment (WampServer or Docker)
• All users are based in Pakistan and file under FBR tax regulations
• The tax year follows Pakistan's fiscal calendar: July 1 – June 30
• The default admin credentials (admin / admin123) will be changed immediately upon first deployment
• Users have basic computer literacy and access to a modern browser (Chrome, Firefox, Edge)
• Internet connectivity is not required for core functionality (fully offline-capable)

Constraints

• The system is not intended to replace the official FBR IRIS portal; it is a local management tool
• PHP is excluded from the final tech stack in favor of Python/FastAPI + React for scalability and maintainability (the original PHP prototype informed requirements but is superseded)
• No direct FBR API integration is in scope for Version 1.0
• Mobile application development (React Native) is deferred to a future version
• AI-powered features are out of scope for Version 1.0
• All data remains on-premises; no cloud storage or third-party data sharing

10. Glossary

Document prepared by the stone-tax Engineering Team for Micro Mind | Pakistan | February 2026 This SRD is a living document and will be updated as requirements evolve.