# shakilahmedatik/amar-space architecture

> Architecture diagram of the GitHub repository shakilahmedatik/amar-space, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shakilahmedatik/amar-space
- Repository: https://github.com/shakilahmedatik/amar-space

## Overview

1. This is a Next.js App Router application for property/building management with two main user-facing surfaces: an authenticated admin/dashboard area and a resident-facing “portal” under `app/portal/[flatSlug]`. The root landing site is separate from both.

2. The routing boundary is clear in `app/`: `app/(landing)` for marketing pages, `app/(auth)` for login/register, and `app/(dashboard)` for the main operational system. The dashboard subtree contains domain screens for buildings, flats, renters, bills, payments, issues, maintenance, notices, staff, audit, and admin management.

3. The portal is its own subsystem rather than just a dashboard page. It has dedicated UI components, hooks, and layout pieces under `app/portal/[flatSlug]/_components`, and it talks to portal-specific API routes under `app/api/portal/flat/[slug]`. That suggests a lighter-weight, token/access-code-based resident experience with session handling, registration, and flat-scoped data.

4. Server-side behavior is concentrated in `app/api/` route handlers. The API is organized by domain, not by transport: bills, buildings, flats, issues, maintenance, notices, payments, renters, staff, users, admin, audit, dashboard summaries, registration requests, deposits, settings, and portal operations. Most state-changing workflows are exposed as nested actions such as status changes, assignments, approvals, refunds, terminations, pinning, and QR-code generation.

5. The data layer is built around Drizzle ORM and a relational schema in `lib/db/schema/`. Core entities include users, sessions, roles/permissions, buildings, flats, rental contracts, renters, bills, payments, issues, maintenance requests/comments/attachments, notices, audit logs, registration requests, portal sessions, access codes, and assignment tables. Migration files and a seed script indicate a conventional SQL-backed database with schema evolution managed in-repo.

6. Above the database sits a repository/service split. `lib/repositories/` provides domain persistence access, while `lib/services/` contains business workflows such as billing, deposits, building/flat management, issue/maintenance handling, notices, permissions, role assignment, registration, termination, QR-code generation, and audit logging. That separation is the main backend boundary: repositories fetch/update data; services enforce business rules and cross-entity operations.

7. Authentication and authorization are treated as first-class architecture concerns. There are auth client/guard modules in `lib/auth*`, session tables in the schema, and role/permission models plus overrides. The presence of admin-only routes, staff roles, owner/manager dashboards, and portal sessions implies strong role-based access control across both server routes and UI surfaces.

8. The client-side state/data access layer is split between reusable hooks and typed API wrappers. `hooks/` contains feature hooks for dashboards, bills, buildings, deposits, flats, issues, maintenance, notices, payments, QR codes, registration requests, renters, staff, terminations, and session expiry. `lib/api/` mirrors those domains as client helpers, making the UI talk to backend routes through a consistent abstraction.

9. The UI is composed from shared components rather than being built page-by-page. `components/ui/` contains the primitive design system, `components/layout/` contains app shell navigation and responsive chrome, and feature-specific widgets exist for QR codes, deposits, and the landing page. The portal has its own component family because its interaction model, language toggle, and session-expiry handling differ from the admin dashboard.

10. Internationalization is built into the app, not bolted on. `lib/i18n/` contains English and Bangla translations plus context/hooks, and portal/dashboards both use language toggle components. That means the architecture supports localized content and locale-aware UI text across key user flows.

11. QR codes are a distinct cross-cutting capability. There are utilities in `lib/qr-code-utils.ts`, API endpoints for building/flat QR-code generation, and dedicated UI for preview, sizing, bulk download, and dialogs. This likely supports printable access/identification artifacts tied to buildings or flats.

12. The repo also includes operational and audit support: `app/api/audit`, audit log schema, analytics events, and dashboard summary endpoints. These indicate that visibility into actions and tenant/building activity is part of the domain model, not an afterthought.

13. Quality and maintenance tooling is significant. The repo includes Biome, Vitest, property-based tests, and a `knip` report for dependency analysis. There are also architecture guidance docs under `docs/` and automation-related files under `.agents/`, which suggests the codebase is maintained with a strong emphasis on conventions and static discipline.

14. Infrastructure-wise, this is a containerizable Next.js app: there is a `Dockerfile`, `.env.example`, and standard Next config. The runtime is the Next.js server plus browser clients, with persistence and auth-backed state handled through the database and API routes rather than a separate backend service.

Main entry points: [`lib/services`](https://github.com/shakilahmedatik/amar-space/tree/main/lib/services) (Services), [`app/(dashboard)`](https://github.com/shakilahmedatik/amar-space/tree/main/app/(dashboard)) (Dashboard), [`app/portal/[flatSlug]`](https://github.com/shakilahmedatik/amar-space/tree/main/app/portal/[flatSlug]) (Portal), [`app/api/portal`](https://github.com/shakilahmedatik/amar-space/tree/main/app/api/portal) (Portal API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["App surfaces"]
  node_node_landing["Landing<br/>marketing routes"]
  node_node_auth["Auth<br/>login/register routes"]
  node_node_dashboard["Dashboard<br/>ops routes"]
  node_node_portal["Portal<br/>resident surface"]
end

subgraph group_grp_api["Server API"]
  node_node_api_domain["Domain API<br/>workflow routes"]
  node_node_api_portal["Portal API<br/>resident routes"]
  node_node_api_auth["Auth API<br/>session handler<br/>[[...all]]"]
  node_node_api_admin["Admin API<br/>privileged routes"]
end

subgraph group_grp_core["Core backend"]
  node_node_schema[("Schema<br/>drizzle models")]
  node_node_repos["Repositories<br/>data access"]
  node_node_services["Services<br/>business workflows"]
  node_node_auth_core["Auth core<br/>clients and guards<br/>[auth.ts]"]
  node_node_shared["Shared domain<br/>validation and helpers"]
  node_node_i18n["I18n<br/>translations"]
  node_node_qr{{"QR system<br/>cross-cutting capability<br/>[qr-code-utils.ts]"}}
end

subgraph group_grp_ui["Client UI"]
  node_node_ui["UI kit<br/>shared components"]
  node_node_layouts["Layouts<br/>shell components"]
  node_node_hooks["Hooks"]
  node_node_client_api["API clients<br/>typed wrappers"]
end

node_node_landing -->|"renders with"| node_node_ui
node_node_auth -->|"uses"| node_node_auth_core
node_node_dashboard -->|"uses"| node_node_layouts
node_node_portal -->|"uses"| node_node_layouts
node_node_dashboard -->|"fetches via"| node_node_hooks
node_node_portal -->|"fetches via"| node_node_hooks
node_node_hooks -->|"wraps"| node_node_client_api
node_node_client_api -->|"calls"| node_node_api_domain
node_node_client_api -->|"calls"| node_node_api_portal
node_node_api_auth -->|"integrates"| node_node_auth_core
node_node_api_admin -->|"orchestrates"| node_node_services
node_node_api_domain -->|"orchestrates"| node_node_services
node_node_api_portal -->|"orchestrates"| node_node_services
node_node_services -->|"reads/writes"| node_node_repos
node_node_repos -->|"maps to"| node_node_schema
node_node_services -->|"uses"| node_node_qr
node_node_services -->|"shares rules"| node_node_shared
node_node_api_portal -->|"validates with"| node_node_shared
node_node_dashboard -->|"localizes"| node_node_i18n
node_node_portal -->|"localizes"| node_node_i18n
node_node_qr -->|"presents via"| node_node_ui
node_node_auth_core -->|"stores in"| node_node_schema

click node_node_landing "https://github.com/shakilahmedatik/amar-space/tree/main/app/(landing)"
click node_node_auth "https://github.com/shakilahmedatik/amar-space/tree/main/app/(auth)"
click node_node_dashboard "https://github.com/shakilahmedatik/amar-space/tree/main/app/(dashboard)"
click node_node_portal "https://github.com/shakilahmedatik/amar-space/tree/main/app/portal/[flatSlug]"
click node_node_api_domain "https://github.com/shakilahmedatik/amar-space/tree/main/app/api"
click node_node_api_portal "https://github.com/shakilahmedatik/amar-space/tree/main/app/api/portal"
click node_node_api_auth "https://github.com/shakilahmedatik/amar-space/blob/main/app/api/auth/[...all]"
click node_node_api_admin "https://github.com/shakilahmedatik/amar-space/tree/main/app/api/admin"
click node_node_schema "https://github.com/shakilahmedatik/amar-space/tree/main/lib/db/schema"
click node_node_repos "https://github.com/shakilahmedatik/amar-space/tree/main/lib/repositories"
click node_node_services "https://github.com/shakilahmedatik/amar-space/tree/main/lib/services"
click node_node_auth_core "https://github.com/shakilahmedatik/amar-space/blob/main/lib/auth.ts"
click node_node_shared "https://github.com/shakilahmedatik/amar-space/tree/main/lib/shared"
click node_node_i18n "https://github.com/shakilahmedatik/amar-space/tree/main/lib/i18n"
click node_node_ui "https://github.com/shakilahmedatik/amar-space/tree/main/components/ui"
click node_node_layouts "https://github.com/shakilahmedatik/amar-space/tree/main/components/layout"
click node_node_hooks "https://github.com/shakilahmedatik/amar-space/tree/main/hooks"
click node_node_client_api "https://github.com/shakilahmedatik/amar-space/tree/main/lib/api"
click node_node_qr "https://github.com/shakilahmedatik/amar-space/blob/main/lib/qr-code-utils.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_landing,node_node_auth,node_node_dashboard,node_node_portal toneBlue
class node_node_api_domain,node_node_api_portal,node_node_api_auth,node_node_api_admin toneAmber
class node_node_schema,node_node_repos,node_node_services,node_node_auth_core,node_node_shared,node_node_i18n,node_node_qr toneMint
class node_node_ui,node_node_layouts,node_node_hooks,node_node_client_api toneRose
```

## Components

### App surfaces

Next.js route groups and resident portal

- [Landing](https://github.com/shakilahmedatik/amar-space/tree/main/app/(landing)): marketing routes · Public site and landing pages · `app/(landing)`
- [Auth](https://github.com/shakilahmedatik/amar-space/tree/main/app/(auth)): login/register routes · Authentication entry pages · `app/(auth)`
- [Dashboard](https://github.com/shakilahmedatik/amar-space/tree/main/app/(dashboard)): ops routes · Operational admin and staff experience · `app/(dashboard)`
- [Portal](https://github.com/shakilahmedatik/amar-space/tree/main/app/portal/[flatSlug]): resident surface · Flat-scoped resident experience and session UI · `app/portal/[flatSlug]`

### Server API

Route handlers organized by domain and workflow

- [Domain API](https://github.com/shakilahmedatik/amar-space/tree/main/app/api): workflow routes · CRUD and workflow endpoints for buildings, bills, issues, maintenance, notices, payments, renters, staff, and settings · `app/api`
- [Portal API](https://github.com/shakilahmedatik/amar-space/tree/main/app/api/portal): resident routes · Access-code, session, registration, notices, issues, and renter-data endpoints · `app/api/portal`
- [Auth API](https://github.com/shakilahmedatik/amar-space/blob/main/app/api/auth/[...all]): session handler · Authentication transport and session endpoints · `app/api/auth/[...all]`
- [Admin API](https://github.com/shakilahmedatik/amar-space/tree/main/app/api/admin): privileged routes · Admin dashboard and user/owner management endpoints · `app/api/admin`

### Core backend

Persistence, services, auth, and shared domain logic

- [Schema](https://github.com/shakilahmedatik/amar-space/tree/main/lib/db/schema): drizzle models · Relational entities for users, buildings, flats, contracts, renters, billing, issues, maintenance, notices, sessions, and access control · `lib/db/schema`
- [Repositories](https://github.com/shakilahmedatik/amar-space/tree/main/lib/repositories): data access · Domain persistence layer for querying and updating records · `lib/repositories`
- [Services](https://github.com/shakilahmedatik/amar-space/tree/main/lib/services): business workflows · Cross-entity rules for billing, deposits, issues, maintenance, notices, QR codes, registration, permissions, and terminations · `lib/services`
- [Auth core](https://github.com/shakilahmedatik/amar-space/blob/main/lib/auth.ts): clients and guards · Authentication client, guards, sessions, and role-based access control · `lib/auth.ts`
- [Shared domain](https://github.com/shakilahmedatik/amar-space/tree/main/lib/shared): validation and helpers · Common portal validation, roles, formatting, errors, and utilities · `lib/shared`
- [I18n](https://github.com/shakilahmedatik/amar-space/tree/main/lib/i18n): translations · English and Bangla text, locale context, and language handling · `lib/i18n`
- [QR system](https://github.com/shakilahmedatik/amar-space/blob/main/lib/qr-code-utils.ts): cross-cutting capability · QR generation, preview, download, and related utilities · `lib/qr-code-utils.ts`

### Client UI

Shared components, hooks, and browser API wrappers

- [UI kit](https://github.com/shakilahmedatik/amar-space/tree/main/components/ui): shared components · Primitive design system and layout chrome used across app surfaces · `components/ui`
- [Layouts](https://github.com/shakilahmedatik/amar-space/tree/main/components/layout): shell components · Dashboard, auth, navigation, and responsive app shells · `components/layout`
- [Hooks](https://github.com/shakilahmedatik/amar-space/tree/main/hooks): client data hooks · Feature hooks for dashboard, portal, billing, QR, renters, staff, and expiry state · `hooks`
- [API clients](https://github.com/shakilahmedatik/amar-space/tree/main/lib/api): typed wrappers · Browser-side helpers for calling domain and portal endpoints · `lib/api`

## Connections

- Landing → UI kit: renders with · Landing pages are composed from shared UI primitives
- Auth → Auth core: uses · Login and register flow through auth client and guards
- Dashboard → Layouts: uses · Dashboard screens share the operational shell
- Portal → Layouts: uses · Resident experience uses its own portal layout and chrome
- Dashboard → Hooks: fetches via · Dashboard views rely on feature hooks for server data
- Portal → Hooks: fetches via · Portal screens use resident-specific hooks
- Hooks → API clients: wraps · Hooks call typed client API helpers
- API clients → Domain API: calls · Browser helpers invoke domain route handlers
- API clients → Portal API: calls · Portal helpers invoke resident route handlers
- Auth API → Auth core: integrates · Auth route handlers depend on auth/session infrastructure
- Admin API → Services: orchestrates · Admin endpoints trigger business workflows
- Domain API → Services: orchestrates · Domain endpoints delegate to services
- Portal API → Services: orchestrates · Portal endpoints use flat-scoped workflows and validation
- Services → Repositories: reads/writes · Services persist through repository abstractions
- Repositories → Schema: maps to · Repositories operate over Drizzle schema tables
- Services → QR system: uses · QR generation is driven from service workflows
- Services → Shared domain: shares rules · Services reuse validation, roles, errors, and helpers
- Portal API → Shared domain: validates with · Portal routes use shared slug and registration validation
- Dashboard → I18n: localizes · Dashboard UI supports language toggling and translations
- Portal → I18n: localizes · Portal UI is localized independently of dashboard flows
- QR system → UI kit: presents via · QR feature has dedicated dialogs, previews, and controls
- Auth core → Schema: stores in · Authentication state is backed by session and role tables