Skip to main content

Law Firm Management System - Architecture Documentation

Welcome to the architecture documentation for the Law Firm Management System. This directory contains comprehensive technical specifications, database schemas, and architectural diagrams.

📚 Documentation Index​

1. Database Design​

  • Database Schema (DBML) - Complete entity-relationship diagram with 23 slices covering all system entities
    • Multi-tenant law firm management
    • Logto-integrated authentication & RBAC
    • Case & client management
    • Time tracking & billing
    • Document management
    • Appointments & collaboration
    • Partner firms & cooperation
    • Performance reviews & bonuses
    • ERP integration

2. API Specifications​

  • User API Specification - Comprehensive technical specification for the User Portal API

    • Authentication & Authorization
    • All 10 API modules (Profile, Cases, Clients, Documents, etc.)
    • Data models & schemas
    • Error handling & status codes
    • Performance & scalability
    • Security considerations
    • Deployment & monitoring

  • User API OpenAPI Spec - Machine-readable OpenAPI 3.1 specification

    • 40+ endpoints
    • Request/response schemas
    • Authentication flows
    • Interactive documentation (Swagger UI / ReDoc)

  • Admin API OpenAPI Spec - Administrative operations API

    • Firm provisioning
    • User management
    • System configuration
    • Support access sessions

3. Architecture Models​

  • C4 Architecture Models - Multi-level architecture diagrams
    • Level 1: System Context - Users, external systems, boundaries
    • Level 2: Container Diagram - Technology stack, services, databases
    • Level 3: Component Diagram - Internal structure of User API
    • Level 4: Code Examples - Implementation patterns
    • Deployment architecture
    • Security architecture
    • Monitoring & observability

🏗️ System Overview​

High-Level Architecture​

┌─────────────────────────────────────────────────────────────┐
│                        Users                                 │
│  (Lawyers, Paralegals, Staff, Clients, Partners)           │
└─────────────────────┬───────────────────────────────────────┘
                      │ HTTPS/JSON
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                   API Gateway                                │
│  (Authentication, Rate Limiting, Routing)                   │
└─────────┬───────────────────────────────────────────────────┘
          │
   ┌──────┴──────┐
   │             │
   ▼             ▼
┌──────────┐  ┌──────────┐
│ User API │  │Admin API │
│  (Core)  │  │(Platform)│
└────┬─────┘  └────┬─────┘
     │             │
     └──────┬──────┘
            │
    ┌───────┴────────┐
    │                │
    ▼                ▼
┌──────────┐    ┌─────────┐
│PostgreSQL│    │  Redis  │
│(Primary) │    │ (Cache) │
└──────────┘    └─────────┘

Key Architectural Principles​

  1. Multi-Tenant by Design

    • Firm-level isolation (row-level security)
    • Shared infrastructure, isolated data
    • Per-firm customization support

  2. Logto-Integrated Authentication

    • External identity provider (Logto)
    • OAuth 2.0 / OIDC flows
    • JWT bearer tokens
    • Organization-based access

  3. Fine-Grained RBAC

    • Role-based permissions (PERMISSIONS, ROLES)
    • User role assignments (scoped by firm/case/org unit)
    • Resource access grants (polymorphic ACLs)
    • Field-level permissions

  4. Event-Driven Architecture

    • Domain events published to message queue
    • Asynchronous processing (notifications, integrations)
    • Audit trail for compliance
    • Eventual consistency

  5. Microservices (Modular Monolith)

    • Clear service boundaries
    • Shared database (transitioning to separate DBs)
    • RESTful APIs with JSON
    • gRPC for inter-service communication

🔐 Security & Compliance​

Authentication Flow​

User → Login Request → Logto (IdP)
                         │
                         ▼
                    JWT Token
                         │
                         ▼
User API ← Validate Token ← Auth Service
    │
    ▼
Permission Check (RBAC)
    │
    ▼
Business Logic

Compliance Standards​

  • GDPR: Data export, right to erasure
  • SOC 2 Type II: Annual audit
  • ABA Model Rules: Attorney-client privilege protection
  • PCI DSS: (if storing payment cards) Tokenization via Stripe

Security Features​

  • TLS 1.3 encryption in transit
  • AES-256 encryption at rest
  • Field-level encryption (SSN, DOB)
  • Audit logging (immutable)
  • Rate limiting (per user/firm)
  • CSRF protection
  • SQL injection prevention (ORM)
  • XSS protection (CSP headers)

📊 Database Schema Highlights​

Core Tables (23 Slices)​

SliceTablesPurpose
0LAW_FIRMSTenant boundary
1AUTH_USERS, LOGTO_*, FIRM_USER_PROFILESAuthentication & user management
2ORG_UNITS, POSITIONS, REPORTING_LINESOrganizational structure
3ARTICLES, SPECIALTIESContent & expertise
4PERFORMANCE_REVIEWS, BONUS_AWARDSHR & compensation
5CLIENTS, CLIENT_CONTACTS, CLIENT_USERSClient management
5ACASES, CASE_BUDGETSCore case management
6PARTNER_FIRMS, PARTNER_ATTORNEYSPartner network
7CASE_*_ROLE_TYPESRole catalogs
8CASE_ATTORNEYS, CASE_CLIENTSCase assignments
9PARTNER_ATTORNEY_USERSPartner portal logins
10PERMISSIONS, ROLES, USER_ROLE_ASSIGNMENTSRBAC system
11BILLING_ACTIVITY_CODES, EXPENSE_CATEGORIESBilling catalogs
12LAWYER_RATE_PLANS, CASE_RATE_PLAN_SELECTIONSPricing engine
13LAWYER_TIME_ENTRIES, EXPENSE_ENTRIESTime & expense tracking
14INVOICES, PAYMENTS, CREDIT_NOTESAccounts receivable
16PARTNER_BILLSPartner accounts payable
17ERP_EXPORT_QUEUE, ERP_ACCOUNT_MAPPINGSERP integration
18VENDORS, FIRM_OPEXFirm operating expenses
19APPOINTMENTS, APPOINTMENT_ATTENDEESScheduling
20SUPPORT_ACCESS_SESSIONS, ADMIN_RESOURCE_LOCKSAdmin tools
21DOCUMENTSDocument management
22NOTIFICATIONSReal-time notifications
23COMMENTSCollaboration

Key Relationships​

LAW_FIRMS (1) ──── (*) FIRM_USER_PROFILES
                         │
                         └── (*) CASES
                               │
                               ├── (*) DOCUMENTS
                               ├── (*) LAWYER_TIME_ENTRIES
                               └── (*) INVOICES

AUTH_USERS (1) ──── (*) FIRM_USER_PROFILES
    │
    ├── (*) USER_ROLE_ASSIGNMENTS ──── (*) ROLES ──── (*) PERMISSIONS
    │
    └── (*) RESOURCE_ACCESS_GRANTS

🚀 API Endpoints Summary​

User Portal API (/v1)​

ModuleEndpointsDescription
ProfileGET/PATCH /meUser profile management
MembersGET /firm/membersColleague directory
CasesGET/POST /cases, GET/PATCH /cases/:idCase CRUD, team management
ClientsGET/POST /clients, GET/PATCH /clients/:idClient management
DocumentsGET/POST /documents, GET/PATCH/DELETE /documents/:idDocument upload/download
AppointmentsGET/POST /appointments, GET/PATCH/DELETE /appointments/:idScheduling
Time EntriesGET/POST /time-entries, POST /time-entries/:id/submitTime tracking
InvoicesGET /invoices, GET /invoices/:idInvoice viewing (read-only)
NotificationsGET /notifications, POST /notifications/:id/mark-readActivity feed
CommentsGET/POST /comments, PATCH/DELETE /comments/:idCollaboration

Total: 40+ endpoints

Admin API (/admin/v1)​

ModuleEndpointsDescription
FirmsGET/POST /firmsFirm provisioning
UsersPOST /users, POST /users/:id/rolesUser management
AccessPOST /support-access-sessionsAdmin impersonation
SyncPOST /sync/logtoLogto synchronization

Total: 30+ endpoints

📈 Performance Targets​

MetricTarget (p95)
Simple GET (single resource)< 100ms
List GET (paginated)< 300ms
POST/PATCH (writes)< 500ms
Search (full-text)< 1000ms
Document upload (presigned URL)< 200ms

Scalability​

  • Concurrent Users: 10,000+
  • Database Size: 1TB+ (with partitioning)
  • Document Storage: 10TB+ (S3)
  • Request Rate: 10,000 req/sec (peak)

🛠️ Technology Stack​

Backend​

  • Runtime: Node.js 20 LTS
  • Framework: NestJS (TypeScript)
  • ORM: TypeORM / Prisma
  • API Docs: OpenAPI 3.1 / Swagger

Data Layer​

  • Primary DB: PostgreSQL 15 (RDS Multi-AZ)
  • Cache: Redis 7 (ElastiCache cluster mode)
  • Search: Elasticsearch 8
  • Queue: AWS SQS / RabbitMQ

Frontend​

  • Web: React 18 + TypeScript
  • Mobile: React Native
  • State: Redux Toolkit / Zustand
  • UI: Material-UI / Tailwind CSS

Infrastructure​

  • Cloud: AWS
  • Containers: Docker + ECS Fargate / Kubernetes
  • CDN: CloudFront
  • Storage: S3
  • Auth: Logto (external SaaS)

DevOps​

  • CI/CD: GitHub Actions
  • IaC: Terraform / CloudFormation
  • Monitoring: CloudWatch + Prometheus + Grafana
  • Logging: CloudWatch Logs + Elasticsearch + Kibana
  • Tracing: AWS X-Ray + Jaeger
  • Alerting: PagerDuty + Slack

🧪 Testing Strategy​

Test Coverage​

  • Unit Tests: 85%+ (Jest)
  • Integration Tests: Key flows (Supertest)
  • E2E Tests: Critical paths (Playwright)
  • Load Tests: 1000 concurrent users (k6)
  • Security Tests: OWASP ZAP, Snyk

Test Environments​

  • Development: Auto-deployed from main
  • Staging: Production mirror
  • Production: Blue-green deployments

📖 Getting Started​

For Developers​

  1. Read the API Specification

  2. Understand the Architecture

  3. Set Up Local Environment

    # Clone repository
    git clone https://github.com/your-org/law-firm-api

    # Install dependencies
    npm install

    # Set up database
    docker-compose up -d postgres redis
    npm run migration:run

    # Start development server
    npm run start:dev

  4. Explore Interactive Docs

For Architects​

  1. Review C4 Architecture Models
  2. Examine Database Schema - visualize at https://dbdiagram.io
  3. Study authentication flow in User API Spec
  4. Understand RBAC system in Database Schema - Slice 10

For Product Managers​

  1. Browse User API Endpoints
  2. Review user flows in C4 Models - Data Flow Diagrams
  3. Understand permissions in API Spec - Authorization

🤝 Contributing​

Documentation Updates​

  • Update OpenAPI specs when adding/modifying endpoints
  • Regenerate docs: npm run openapi:generate
  • Update C4 diagrams when architecture changes
  • Keep database.dbml in sync with migrations

Code Standards​

  • TypeScript strict mode
  • ESLint + Prettier
  • Conventional Commits
  • Code review required (2 approvals)

📞 Support​

  • Documentation Issues: Open GitHub issue with docs label
  • API Questions: #api-development Slack channel
  • Architecture Discussion: #architecture Slack channel
  • On-Call: PagerDuty escalation for production issues

📄 License​

Proprietary - All Rights Reserved © 2024 Your Law Firm

Last Updated: 2024-10-26 Maintained By: Platform Engineering Team Version: 1.0.0