shakilahmedatik/amar-space

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.