Start at the root
README.md— it is the canonical entry point and documentation portal for the whole repository (hero, project metrics, architecture diagrams, feature matrix, and the grouped documentation hub). This file is the detailed index it links into.
This is the single source of truth for all technical documentation for the Abir Barman portfolio project. Project management (tasks, sprints, roadmap tracking, meeting notes) lives in Notion — see notion-vs-markdown.md for the split.
Status: complete as of the 2026-07-03 documentation audit — every directory below is populated, all 896 internal links resolve, and all pre-existing content was corrected against the real codebase (see
appendices/technical-debt-register.md). Seeappendices/documentation-coverage-report.mdfor the full coverage/quality scorecard andappendices/README.mdfor all health reports.
| If you are... | Start here |
|---|---|
| A new contributor setting up locally | development/setup-and-workflow.md |
| Trying to understand the system design | architecture/overview.md |
| Building against the API | api/rest-api-reference.md |
| Working on the database/content model | database/schema-reference.md |
| Deploying or managing infra | deployment/hosting-guide.md |
| Using the CMS/admin panel | cms/admin-panel-reference.md |
| Reviewing security posture | security/ |
| A recruiter/client wanting the high-level picture | architecture/overview.md + root README.md |
| Directory | Contents |
|---|---|
architecture/ |
System design, layer boundaries, rendering strategy, auth flow, CORS, future architecture |
development/ |
Local setup, workflow, coding standards, git conventions, troubleshooting |
frontend/ |
Frontend-specific structure and conventions |
backend/ |
Backend-specific structure and conventions |
pages/ |
One doc per route — purpose, SEO, data sources, states |
features/ |
One doc per product feature — contact form, notifications, theming, etc. |
components/ |
One doc per reusable component, grouped by sections/, admin/, ui/ |
layouts/ |
Root layout, admin layout, page-transition template |
hooks/ |
Custom hooks (currently none exist — see the gap noted there) |
utilities/ |
lib/api.ts, lib/types.ts, lib/date.ts, backend lib/ |
styles/ |
Tailwind/CSS variable conventions |
design-system/ |
Design tokens, typography, component visual guidelines |
animations/ |
Framer Motion animation principles and timing |
cms/ |
Admin panel / custom CMS reference |
deployment/ |
Vercel, Render, Supabase hosting, environment variables |
security/ |
Auth, secrets, rate limiting, OWASP checklist |
performance/ |
Image/font optimization, code splitting, Core Web Vitals |
testing/ |
Testing strategy (currently no automated tests exist) |
api/ |
Full REST API reference |
database/ |
Prisma schema reference |
assets/ |
Favicon/branding asset inventory |
guides/ |
Task-oriented how-tos (e.g. "add a new content section") |
tutorials/ |
Step-by-step walkthroughs for newcomers |
templates/ |
Reusable templates for every doc type in this project |
adr/ |
Architecture Decision Records |
standards/ |
Style guide, markdown/naming/folder conventions, review process |
roadmap/ |
Future architecture and documentation roadmap |
references/ |
External services, third-party libraries, glossary links |
glossary/ |
Project-specific terminology |
decisions/ |
Running decision log (lighter-weight than formal ADRs) |
releases/ |
Release notes index (root CHANGELOG.md is canonical) |
diagrams/ |
Mermaid diagram sources referenced by architecture docs |
appendices/ |
Full audit report, technical debt register, documentation health reports |
Per the documentation philosophy for this project, only these files stay at the repository root: README.md, LICENSE, CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md. Everything else technical lives under /docs.