Chapter 1 - Master Software Requirements Specification

1. Document Control

Revision history

No sign-off records, author names, or approvals have been invented. Stakeholder approval is explicitly not granted by this document.

2. Executive Summary

TKAMOL is an enterprise-grade, multi-workspace (multi-tenant) legal-operations platform for law firms and professional services teams. It is built on Laravel 12 with a React 19 SPA delivered via Inertia.js. The platform unifies project/case management, task tracking (Kanban boards), time tracking and timesheet approvals, expense management and budgeting, invoice generation and collection via 30+ payment gateways, client/company/contact management, legal-bug tracking, IMAP-based email inbox with AI-driven triage and assignment, AI assistant (Gemini) chat, WhatsApp/Slack/Telegram notifications, Zoom meetings, and SaaS billing (plans, plan orders, coupons, referrals). Frontend is supported in 16 enabled locales (actual configuration — see §7) with full RTL.

3. Business Context and Objectives

• Business problem: law firms manage cases, deadlines, teams, clients, billing, and inbound client email on disconnected tools, losing traceability and time.
• Business objective: single unified system of record for case lifecycle, time and expense, billing, and team communication.
• Business objective: safer handling of legal-budget approval workflows (submitters → reviewers → approver) and invoice payment collection.
• Business objective: automated ingestion of inbound legal email (Gmail/IMAP) into projects/tasks and assignment to the right team member via AI.
• Business objective: allow a SaaS operator to host multiple law firms as separate companies/tenants with subscription plans, trial, plan-change requests.
• Known business constraints (from code):

1. Non-SaaS mode removes plan-gating, billing, companies admin, and coupons — config('app.is_saas') (config/app.php).
2. Demo mode blocks state-changing HTTP verbs via DemoModeMiddleware — config('app.is_demo').
3. All role permissions are hardcoded in PermissionSeeder and RoleSeeder; 286 permissions across 31 modules.

• Confirmed vs inferred: the core business objectives above are inferred from implementation; if the project was commissioned against signed specifications, those remain the source of truth. Stakeholder confirmation needed.

4. Scope

Confirmed in-scope (implemented & wired in routes + pages + models)

Authentication and registration, multi-workspace tenancy, users/roles/permissions, projects with milestones/notes/attachments, tasks with Kanban stages/comments/checklists/attachments/templates, bugs with statuses/comments/attachments, timesheets/entries/timer/approvals/reports, budgets/revisions/categories, expenses/approvals/dashboards/workflows/receipts/recurring, invoices/items/payments/public checkout through 33 gateways, contacts/companies/newsletters, email templates/notification templates, email inbox (IMAP + rules + AI), AI agent chat (Gemini), WhatsApp/Slack/Telegram/Zoom integrations, dashboards and reports, multi-language/RTL, media library, performance evaluations, landing page / custom pages.

Potential / proposed (only referenced but not wired)

• Referral program — app/Http/Controllers/ReferralController.php exists, but all referral routes are commented out in routes/web.php lines 521–527. Implementation status: backend present, UI page exists (referral/index.tsx), routes disabled.
• Social login / Google2FA — users.google2fa_enable/secret and created_by columns; only 'verified' middleware gated on emailVerification setting. No social-login controller observed.
• VCard import/export — mentioned in README; export route not found in web.php for vCards.
• Browser push notifications / cloud backup / SSO — no evidence.
• Expense report CSV export — ExpenseReportController::export returns {"message":"Export functionality coming soon"} (line 155) — placeholder, not implemented.
• Slack settings GET endpoint — route slack.settings (GET) points to SlackSettingsController::getSettings, which does not exist (only update, testWebhook). Minor documentation/feature gap.

Out of scope

No explicit signed statement of scope was found in the repository. A BUSINESS.md (31 KB) file exists and should be treated as the authoritive business proposal. (Its contents were not quoted in this draft; cross-read recommended.)

5. Stakeholders and User Classes

Source: database/seeders/RoleSeeder.php and PermissionSeeder.php (286 permissions).

Access enforcement is roles-based (Spatie in SaaS mode, in non-SaaS mode uses the workspace_members.role column without Spatie — see System doc §4). End users can only access their current workspace (users.current_workspace_id).

6. Functional Requirements

Full canonical list: Part I - Software Requirements Specification, Chapter 2 (Functional Requirements Register). Summary modules:

• FR-AUTH (authentication & registration, 15 requirements)
• FR-WORKSPACE (workspaces & members, 12 reqs)
• FR-COMPANY (SaaS companies/billing, 14 reqs)
• FR-PROJECT (project lifecycle, 18 reqs)
• FR-TASK (tasks & kanban, 15 reqs)
• FR-BUG (bug tracking, 7 reqs)
• FR-TIMESHEET (timesheets/entries/timer/approvals, 11 reqs)
• FR-BUDGET (budgets & revisions, 8 reqs)
• FR-EXPENSE (expenses & workflow, 13 reqs)
• FR-INVOICE (invoices & payments, 14 reqs)
• FR-MEDIA (media library, 4 reqs)
• FR-COMM (contacts, newsletters, notifications, 7 reqs)
• FR-EMAIL (IMAP inbox & rules, 14 reqs)
• FR-AI-EMAIL (Gemini-based email assignment, 9 reqs)
• FR-AI-AGENT (in-app assistant, 10 reqs)
• FR-REPORTS (dashboards & reports, 8 reqs)
• FR-ADMIN (Plans, Coupons, Roles/Permissions, Languages, Landing CMS, templates, integrations settings, 22 reqs)
• FR-INT (WhatsApp/Slack/Telegram/Zoom/email delivery, 13 reqs)

Total: 214 functional requirements, each labelled Implemented & Verified / Partially Implemented / Present but Unverified / Not Found / Stakeholder Confirmation Required.

7. Non-Functional Requirements

Full canonical list: Part I - Software Requirements Specification, Chapter 3 (Non-Functional Requirements Register). Key points:

• Security: session-based auth, CSRF exceptions only for callbacks, owned workspace guard; notable gaps: plaintext fallback IMAP password in config/imap.php, password hashes nullable in migration, no .env shipped, demo mode.
• Performance: no stated SLA; indexes present on audit/migration; withoutOverlapping() scheduled tasks.
• Availability: no redundancy/uptime SLA defined (To Be Confirmed).
• Accessibility & locale: 16 locales enabled (ar, da, de, en, es, fr, he, hi, it, ja, nl, pl, pt, ru, tr, zh-CN) per resources/lang/language.json, of paths claimed 22 in README (mismatch).
• Maintainability: MVC+Service+Repository; conventional routes; 380 JS files. Test coverage none at app level (no tests/ directory). Major NFR gap.

8. Business Rules

9. Use Cases

Full text: Part I - Software Requirements Specification, Chapter 4 (Use Cases and Acceptance Criteria). Core ones: UC-REG (register/verify), UC-WS-SWITCH, UC-PROJECT-CREATE, UC-TASK-BOARD, UC-TIMESHEET-APPROVE, UC-EXPENSE-APPROVAL, UC-INVOICE-CHECKOUT, UC-EMAIL-INGEST-AI, UC-AI-CHAT, UC-EVAL-FIRM.

10. Data Requirements

• Business data ownership: Workspace is the tenancy root; all workspace_id columns are either explicit or implied via project_id. Sub-entities (tasks, expenses) are scoped via parent project.
• Sensitive data categories handled: IMAP passwords (encrypted), API keys in Setting, payment gateway credentials, legal content in email bodies, invoices/clients, audit logs, performance metrics.
• Validation/integrity: foreign keys declared in migrations; unique keys (email, slug, invoice number, unique email+workspace, payment settings); unique (workspace, month) on AI token usage.
• Data retention/deletion: many models use softDeletes? Only projects (and tasks? Migration shows tasks with softDeletes per manual). Deletion cascades: must be audited per table. Stakeholder confirmation needed for retention period/regulatory requirements (e.g., legal records retention).
• Multi-language: TaskTemplate/EmailTemplate/NotificationTemplate implement per-language child tables.

11. External Interfaces

12. Constraints, Assumptions, Dependencies

• PHP ^8.2, Laravel Framework ^12, Node ESM, Vite 6.
• DB: MySQL (production assumed) or SQLite (local). Redis optional.
• Queue worker recommended php artisan queue:work --tries=3 --timeout=600.
• Scheduler requires cron.
• WebSocket is not used (no broadcast standard config beyond default).
• No .env.example tracked — install scripts expect it and fallback is broken; operational risk.
• Demo/extension of platform expects assets via build-ui/ remote builder.

13. Acceptance Criteria

See Part I - Software Requirements Specification, Chapter 4 (Use Cases and Acceptance Criteria). Criteria follow Given/When/Then and are required to be validated by QA; no acceptance claim is made here.

14. Requirements Traceability

See Part I - Software Requirements Specification, Chapter 5 (Requirements Traceability). Includes IDs, module/delivery, source, implementation status.

15. Open Questions and Stakeholder Decisions (must be resolved before SRS becomes contractual)

1. Scope authority: which is the signed spec — the BUSINESS.md (31 KB) file, or stakeholder verbal requirements?
2. Roles: is owner read-only or full-access (seed shows full company grants)? (database/seeders/RoleSeeder.php).
3. Languages: README claims 22 languages; app config enables 16. Which is required?
4. Tests: no test suite at all. Minimum coverage threshold to be agreed. (Phase 6 NFR-gating.)
5. Data retention: retention policy & legal records requirements unspecified; required due to multi-tenant legal data.
6. AI cost basis & pricing: AI charges in USD per token; max token limit configuration ai_monthly_price_limit vs ai_monthly_token_limit mismatch.
7. Payment/finance gateway enable flags: only web-push/channel list of 33 gateways. Which should be supported out-of-the-box in UAT?
8. Vocabulary "case" vs "project": domain model calls them projects, UI likely says projects; confirm whether a legal case entity separate from project is needed.
9. Currency accuracy in consultant's monthly reports / invoice currency.
10. Production deployment baseline (managed hosting, no CF/infra declared). See Technical doc.
11. AI model privacy / confidentiality: inbound email body is sent to Gemini — data-sharing acceptance needed by the law firm clients.
12. Cross-user data isolation audit under SOC-equivalent policies — see Security Review.